@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.1669d45

package/analyzer-template/packages/ai/src/lib/dataStructure/ScopeDataStructure.ts

@@ -1,36 +1,117 @@
-/* ScopeDataStructure
+/**
+ * ScopeDataStructure
  *
- * The ScopeDateStructure takes the output of the ASTAnalyzer and merges
- * all scopes to determine a complete schema for the function.
+ * The core engine for CodeYam's static analysis. Takes AST analysis output and
+ * determines the complete data schema for a function by tracking how data flows
+ * through the code.
  *
- * It does two passes through all scopes.
+ * ## High-Level Architecture
  *
- * The first establishes equivalencies,
- * such as implicit parent scope -> nested child scope equivalencies.
+ * ```
+ * ┌─────────────────┐     ┌─────────────────────────────────────────────┐
+ * │  AST Analyzer   │────▶│           ScopeDataStructure                │
+ * │ (per-scope)     │     │                                             │
+ * └─────────────────┘     │  Phase 1: Discovery (onlyEquivalencies)     │
+ *                         │  ├─ Process each scope's analysis           │
+ *                         │  ├─ Build equivalency relationships         │
+ *                         │  └─ Track nested scope hierarchy            │
+ *                         │                                             │
+ *                         │  Phase 2: Schema Building                   │
+ *                         │  ├─ Follow all equivalencies                │
+ *                         │  ├─ Build complete schemas at data sources  │
+ *                         │  └─ Populate equivalencyDatabase            │
+ *                         └─────────────────────────────────────────────┘
+ *                                           │
+ *                                           ▼
+ *                         ┌─────────────────────────────────────────────┐
+ *                         │              Output                          │
+ *                         │  • Function signature schemas               │
+ *                         │  • Return value types                       │
+ *                         │  • External API call schemas                │
+ *                         │  • Data flow (source → usage) mappings      │
+ *                         └─────────────────────────────────────────────┘
+ * ```
  *
- * The second pass follows all equivalencies to build up a complete schema at the
- * source of the data (either the function's signature arguments or an external
- * API call made from within the function). While following the equivalencies the
- * second pass populates the equivalencyDatabase which tracks all equivalent values
- * and provides easy access to determine where data comes from and where it is used
- * to call external functions. This makes it possible to combine schemas between
- * functions to create a complete schema for a dependency tree.
+ * ## Key Concepts
  *
- * There are a number of getter functions that provide easy access to signature data
- * and return values for the function being analyzed and any function called from the
- * function being analyzed.
+ * ### Equivalencies
+ * When code assigns one variable to another (`const user = props.user`), we create
+ * an "equivalency" linking the two paths. Following these links lets us trace data
+ * back to its source (function arguments or API returns).
+ *
+ * ### Schema Paths
+ * Dot-separated strings describing data structure:
+ * - `signature[0].user.id` - First arg's user.id property
+ * - `items[].name` - name property of array elements
+ * - `functionCallReturnValue(fetch).data` - Return from fetch() call
+ *
+ * ### Two-Phase Processing
+ * 1. **Phase 1 (Discovery)**: `onlyEquivalencies = true`
+ *    - Processes scopes, builds equivalency graph
+ *    - Does NOT populate schemas yet
+ *
+ * 2. **Phase 2 (Schema Building)**: `captureCompleteSchema()`
+ *    - Follows equivalencies to build complete schemas
+ *    - Populates `equivalencyDatabase` for source/usage queries
+ *
+ * ## Key Methods (Entry Points)
+ *
+ * - `constructor(scopeName, scopeText, managers, scopeAnalysis)` - Initialize with root scope
+ * - `addScopeAnalysis(scopeName, text, analysis)` - Add nested scope
+ * - `captureCompleteSchema()` - Trigger Phase 2 processing
+ * - `getSchema({scopeName})` - Get schema for a scope
+ * - `getFunctionSignature({functionName})` - Get function signature schema
+ * - `getSourceEquivalencies()` - Find where data comes from
+ * - `getUsageEquivalencies()` - Find where data is used
+ *
+ * ## Debugging Tips
+ *
+ * - Enable metrics: `addToSchemaCallCount`, `followEquivalenciesCallCount`
+ * - Check `scopeNode.equivalencies` for raw equivalency data
+ * - Use `getEquivalenciesDatabaseEntry(scope, path)` to trace a specific path
+ * - The `visitedTracker` prevents infinite loops - if data is missing, check if
+ *   it was already visited with a different value
+ *
+ * ## Related Files
+ *
+ * - `helpers/` - Extracted utility modules (PathManager, VisitedTracker, etc.)
+ * - `equivalencyManagers/` - Plugins that create equivalencies from AST patterns
+ * - `helpers/README.md` - Overview of the helper module architecture
  */
 
 import { ScopeAnalysis } from '~codeyam/types';
-import {
-  joinParenthesesAndArrays,
-  splitOutsideParenthesesAndArrays,
-} from '../splitOutsideParentheses';
 import { EquivalencyManager } from './equivalencyManagers/EquivalencyManager';
 import fillInSchemaGapsAndUnknowns from './helpers/fillInSchemaGapsAndUnknowns';
+
+/**
+ * Patterns that indicate recursive type structures in schema paths.
+ * Used by hasExcessivePatternRepetition() to detect exponential path blowup.
+ */
+const RECURSIVE_PATH_PATTERNS = [
+  /\.attributes\.properties\[\]/g, // TypeScript AST JSX nodes
+  /\.children\[\]/g, // Tree structures
+  /\.elements\[\]/g, // Array-like structures
+  /\.members\[\]/g, // Class/interface members
+  /\.properties\[\]/g, // Object properties
+  /\.items\[\]/g, // Generic items arrays
+];
 import ensureSchemaConsistency from './helpers/ensureSchemaConsistency';
-import cleanOutBoundary from '../cleanOutBoundary';
 import cleanPath from './helpers/cleanPath';
+import { PathManager } from './helpers/PathManager';
+import {
+  uniqueId,
+  uniqueScopeAndPaths,
+  uniqueScopeVariables,
+} from './helpers/uniqueIdUtils';
+import selectBestValue from './helpers/selectBestValue';
+import { VisitedTracker } from './helpers/VisitedTracker';
+import { DebugTracer } from './helpers/DebugTracer';
+import { BatchSchemaProcessor } from './helpers/BatchSchemaProcessor';
+import {
+  ROOT_SCOPE_NAME,
+  ScopeTreeManager,
+  ScopeTreeNode,
+} from './helpers/ScopeTreeManager';
 import cleanScopeNodeName from './helpers/cleanScopeNodeName';
 import getFunctionCallRoot from './helpers/getFunctionCallRoot';
 import cleanPathOfNonTransformingFunctions from './helpers/cleanPathOfNonTransformingFunctions';
@@ -40,40 +121,13 @@ import type {
   SerializableFunctionCallInfo,
   SerializableFunctionResult,
   SerializableScopeVariable,
+  EnrichedConditionalUsage,
 } from '../worker/SerializableDataStructure';
 
-// import { appendFileSync } from 'node:fs';
-// function writeEquivalencyToFile(
-//   scopeNodeName: string,
-//   path: string,
-//   equivalentScopeNodeName: string,
-//   equivalentPath: string,
-//   newEquivalentPath: string,
-//   equivalencyReason: string,
-// ) {
-//   if ([
-//     'original equivalency'
-//   ].includes(equivalencyReason)) {
-//     return
-//   }
-
-//   appendFileSync('equivalencies.txt', '\n\n');
-//   appendFileSync('equivalencies.txt',
-//     JSON.stringify(
-//       {
-//         newEquivalentPath,
-//         scopeNodeName,
-//         path,
-//         equivalentScopeNodeName,
-//         equivalentPath,
-//         equivalencyReason,
-//       },
-//       null,
-//       2,
-//     ),
-//   );
-// }
-
+/**
+ * ScopeInfo represents a function scope discovered during AST analysis.
+ * Contains the raw analysis data before it's processed into a ScopeNode.
+ */
 export interface ScopeInfo {
   name: string;
   text: string;
@@ -85,48 +139,144 @@ export interface ScopeInfo {
   isStatic?: boolean;
   isClassScope?: boolean;
   analysis?: any;
+  /** For JSX child scopes, the original JSX tag name (e.g., 'ChildViewer') */
+  jsxTagName?: string;
+  /**
+   * Gating conditions detected during JSX extraction (before JSX is simplified).
+   * Maps child component name to conditions that must be true for it to render.
+   * This is populated by processJSXForScope in isolateScopes.ts.
+   */
+  extractedGatingConditions?: {
+    [childComponentName: string]: Array<{
+      path: string;
+      conditionType: 'truthiness' | 'comparison';
+      location: 'if' | 'ternary' | 'logical-and' | 'switch';
+      isNegated?: boolean;
+    }>;
+  };
 }
 
+/**
+ * ScopeNode is the processed representation of a function scope.
+ * Contains the schema and equivalencies built during analysis.
+ *
+ * Key fields:
+ * - `schema`: Map of path → type (e.g., `{ 'user.id': 'string' }`)
+ * - `equivalencies`: Map of path → equivalent paths in other scopes
+ * - `functionCalls`: External function calls made from this scope
+ */
 export interface ScopeNode {
+  /** Unique scope name, may include suffix like `____cyScope0A` for disambiguation */
   name: string;
+  /** Path from root scope to this scope (e.g., ['outer', 'inner']) */
   tree: string[];
+  /** Original source code text of the function */
   text: string;
+  /** Raw AST analysis output */
   analysis: ScopeAnalysis;
+  /** True if this is a static class method */
   isStatic?: boolean;
+  /** The built schema: maps schema paths to type values */
   schema: Record<string, string>;
-  equivalencies: Record<string, ScopeVariable[]>; // Trace data attributes to the source of the data
+  /** Maps local paths to equivalent paths in other scopes (for tracing data flow) */
+  equivalencies: Record<string, ScopeVariable[]>;
+  /** External function calls made from this scope */
   functionCalls: FunctionCallInfo[];
+  /** True if this scope is a function definition (vs. class/module) */
   isFunctionDefinition: boolean;
-  instantiatedVariables?: string[]; // Variables instantiated in this scope
-  parentInstantiatedVariables?: string[]; // Variables instantiated in the parent scope that are available in this scope
+  /** Variables created in this scope (e.g., via `const x = ...`) */
+  instantiatedVariables?: string[];
+  /** Variables from parent scope accessible in this scope */
+  parentInstantiatedVariables?: string[];
 }
 
-export interface ScopeTreeNode {
-  name: string;
-  children: ScopeTreeNode[];
-}
+// Re-export ScopeTreeNode from ScopeTreeManager for backward compatibility
+export type { ScopeTreeNode };
 
+/**
+ * ScopeVariable represents a reference to a specific path in a specific scope.
+ * Used in equivalency chains to track data flow.
+ */
 export interface ScopeVariable {
-  id: number; // Never go through the same equivalency twice
+  /** Unique ID to prevent processing the same equivalency twice */
+  id: number;
+  /** Name of the scope containing this variable */
   scopeNodeName: string;
+  /** Schema path (e.g., 'signature[0].user.id') */
   schemaPath: string;
+  /** Why this equivalency exists (e.g., 'destructuring', 'assignment') */
   equivalencyReason: string;
 }
 
+/**
+ * VariableInfo is the public representation of a tracked variable.
+ * Returned by getter methods like `getVariableInfo()`.
+ */
 export interface VariableInfo {
   name: string;
   equivalentTo?: ScopeVariable[];
   schema: Record<string, string>;
 }
 
+/**
+ * FunctionCallInfo tracks an external function call and its data flow.
+ * Used to understand what data is passed to external APIs.
+ */
 export interface FunctionCallInfo {
+  /** Function name (e.g., 'fetch', 'console.log') */
   name: string;
+  /** How the function was called (e.g., 'fetch(url, options)') */
   callSignature: string;
+  /** Scope where the call was made */
   callScope: string;
-  schema?: Record<string, string>; // For tracking schema of external function calls
-  equivalencies?: Record<string, ScopeVariable[]>; // Trace all signature data back to original source (either root scope signature of functionCallReturnValue of another external function call)
+  /** Schema of arguments passed to the function */
+  schema?: Record<string, string>;
+  /** Traces argument data back to original source */
+  equivalencies?: Record<string, ScopeVariable[]>;
+  /**
+   * All call signatures that were merged into this entry.
+   * When multiple method calls on the same object (e.g., logger.info, logger.debug)
+   * are encountered, they get merged into one FunctionCallInfo but we track all signatures.
+   */
+  allCallSignatures?: string[];
+  /**
+   * Variable names that receive the return value of each call.
+   * For example, in `const result1 = db.select(query1)`, the receiving variable is 'result1'.
+   * This enables generating separate mock data for each call site.
+   */
+  receivingVariableNames?: string[];
+  /**
+   * Maps each call signature to the variable that receives its return value.
+   * For example: { "db.select(query1)": "result1", "db.select(query2)": "result2" }
+   */
+  callSignatureToVariable?: Record<string, string>;
+  /**
+   * Stores individual schemas per call signature BEFORE merging.
+   * When multiple calls to the same function are merged into one FunctionCallInfo,
+   * this preserves each call's distinct schema.
+   * Key is the call signature (e.g., "useFetcher()").
+   * Used internally; converted to perVariableSchemas in toSerializable().
+   */
+  perCallSignatureSchemas?: Record<string, Record<string, string>>;
+  /**
+   * Stores individual return value schemas per receiving variable, BEFORE merging.
+   * When multiple calls to the same function have different return types
+   * (e.g., useFetcher<UserData>() vs useFetcher<ReportData>()), this preserves
+   * each call's distinct schema for mock data generation.
+   * Key is the receiving variable name (e.g., "userFetcher", "reportFetcher").
+   */
+  perVariableSchemas?: Record<string, Record<string, string>>;
 }
 
+/**
+ * EquivalencyValueChainItem tracks a single step in an equivalency chain.
+ * Used internally during schema building to trace data from usage back to source.
+ *
+ * Example chain for `const { user } = props; return user.name;`:
+ * 1. returnValue → user.name (reason: 'return statement')
+ * 2. user.name → props.user.name (reason: 'destructuring')
+ * 3. props.user.name → signature[0].user.name (reason: 'parameter')
+ */
 export interface EquivalencyValueChainItem {
   id: number;
   addToSchemaId?: number;
@@ -145,41 +295,152 @@ export interface EquivalencyValueChainItem {
   traceId?: number;
 }
 
+/**
+ * EquivalencyDatabaseEntry links data sources to their usages.
+ *
+ * After analysis, use `getSourceEquivalencies()` and `getUsageEquivalencies()`
+ * to query this database and understand data flow:
+ * - sourceCandidates: Where the data originates (function args, API returns)
+ * - usages: Where the data is consumed (return values, JSX props, API calls)
+ * - intermediatesOrder: All paths in the chain, ordered by distance from source
+ */
 export interface EquivalencyDatabaseEntry {
   id: number;
+  /** Paths where data originates (signature args, API returns) */
   sourceCandidates: Pick<ScopeVariable, 'schemaPath' | 'scopeNodeName'>[];
+  /** Paths where data is consumed (return values, JSX props) */
   usages: Pick<ScopeVariable, 'schemaPath' | 'scopeNodeName'>[];
+  /** All intermediate paths with their distance from source (0 = source) */
   intermediatesOrder: Record<string, number>;
-  complexSourceEquivalencies: Set<string>; // subsets of this equivalent path that each have different data sources (e.g. the variable analysisEntityPair has a different source for analysisEntityPair.analysis vs analysisEntityPair.entity)
+  /** Paths with multiple distinct sources (e.g., object with props from different origins) */
+  complexSourceEquivalencies: Set<string>;
 }
 
-const ROOT_SCOPE_NAME = 'root';
-
 // DEBUG: Performance metrics
 export let maxEquivalencyChainDepth = 0;
 export let addToSchemaCallCount = 0;
 export let followEquivalenciesCallCount = 0;
+export let followEquivalenciesEarlyExitCount = 0;
+export let followEquivalenciesEarlyExitPhase1Count = 0;
+export let followEquivalenciesWithWorkCount = 0;
+export let addEquivalencyCallCount = 0;
 export function resetScopeDataStructureMetrics() {
   maxEquivalencyChainDepth = 0;
   addToSchemaCallCount = 0;
   followEquivalenciesCallCount = 0;
+  followEquivalenciesEarlyExitCount = 0;
+  followEquivalenciesEarlyExitPhase1Count = 0;
+  followEquivalenciesWithWorkCount = 0;
+  addEquivalencyCallCount = 0;
 }
 
+// Performance: Pre-computed Sets for equivalency reason filtering (O(1) vs O(n))
+const ALLOWED_EQUIVALENCY_REASONS = new Set([
+  'original equivalency',
+  'implicit parent equivalency',
+  'explicit parent equivalency',
+  'transformed non-object function equivalency - original equivalency',
+  'equivalency to external function call',
+  'functionCall to function signature equivalency',
+  'explicit parent signature',
+  'useState setter call equivalency',
+  'non-object function argument function signature equivalency1',
+  'non-object function argument function signature equivalency2',
+  'returnValue to functionCallReturnValue equivalency',
+  '.map() function deconstruction',
+  'useMemo return value equivalent to first argument return value',
+  'useState value equivalency',
+  'Node .then() equivalency',
+  'Explicit array deconstruction equivalency value',
+  'forwardRef equivalency',
+  'forwardRef signature to child signature equivalency',
+  'captured function call return value equivalency',
+  'original equivalency - rerouted via useCallback',
+  'non-object function argument function signature equivalency1 - rerouted via useCallback',
+  'non-object function argument function signature equivalency2 - rerouted via useCallback',
+  'implicit parent equivalency - rerouted via useCallback',
+  'Spread operator equivalency key update: implicit parent equivalency',
+  'Array.from() equivalency',
+  'propagated sub-property equivalency',
+  'propagated function call return sub-property equivalency',
+  'propagated parent-variable equivalency', // Added: propagate child scope equivalencies to parent scope when variable is defined in parent
+  'where was this function called from', // Added: tracks which scope called an external function
+  'MUI DataGrid renderCell params.row equivalency', // Added: links DataGrid renderCell params.row to rows array elements
+  'MUI Autocomplete getOptionLabel option equivalency', // Added: links Autocomplete getOptionLabel callback param to options array
+  'MUI Autocomplete renderOption option equivalency', // Added: links Autocomplete renderOption callback param to options array
+  'MUI Autocomplete option property equivalency', // Added: propagates property accesses from Autocomplete callbacks
+]);
+
+const SILENTLY_IGNORED_EQUIVALENCY_REASONS = new Set([
+  'signature of functionCall',
+  'transformed non-object function equivalency - implicit parent equivalency',
+  'transformed non-object function equivalency - non-object function argument function signature equivalency1',
+  'transformed non-object function equivalency - non-object function argument function signature equivalency2',
+  'transformed non-object function equivalency - equivalency to external function call',
+  'Explicit array deconstruction equivalency key',
+  'transformed non-object function equivalency - useState setter call equivalency',
+  'transformed non-object function equivalency - implicit parent equivalency - rerouted via useCallback',
+  'transformed non-object function equivalency - Array.from() equivalency',
+  'Spread operator equivalency key update: Explicit array deconstruction equivalency value',
+]);
+
 export class ScopeDataStructure {
   debugCount = 0;
   onlyEquivalencies = true;
   equivalencyManagers: EquivalencyManager[] = [];
   scopeNodes: Record<string, ScopeNode> = {};
-  scopeTree: ScopeTreeNode = { name: ROOT_SCOPE_NAME, children: [] };
+  private scopeTreeManager: ScopeTreeManager = new ScopeTreeManager();
   externalFunctionCalls: FunctionCallInfo[] = [];
+
+  // Getter for backward compatibility - returns the tree structure
+  get scopeTree(): ScopeTreeNode {
+    return this.scopeTreeManager.getTree();
+  }
   environmentVariables: string[] = [];
   equivalencyDatabase: EquivalencyDatabaseEntry[] = [];
 
+  /**
+   * Conditional usages collected during AST analysis.
+   * Maps local variable path to array of usages.
+   */
+  private rawConditionalUsages: Record<
+    string,
+    Array<{
+      path: string;
+      conditionType: 'truthiness' | 'comparison' | 'switch';
+      comparedValues?: string[];
+      location: 'if' | 'ternary' | 'logical-and' | 'switch';
+    }>
+  > = {};
+
+  /**
+   * Conditional effects collected during AST analysis.
+   * Tracks what setter calls happen inside conditionals (if, switch, ternary).
+   */
+  private rawConditionalEffects: import('../astScopes/types').ConditionalEffect[] =
+    [];
+
+  /**
+   * Compound conditionals collected during AST analysis.
+   * Groups conditions that must all be true together (e.g., a && b && c).
+   */
+  private rawCompoundConditionals: import('../astScopes/types').CompoundConditional[] =
+    [];
+
+  /**
+   * Gating conditions for child component boundaries.
+   * Maps child component name to the conditions that must be true for it to render.
+   */
+  private rawChildBoundaryGatingConditions: Record<
+    string,
+    import('../astScopes/types').ConditionalUsage[]
+  > = {};
+
   private lastAddToSchemaId = 0;
   private lastEquivalencyId = 0;
   private lastEquivalencyDatabaseId = 0;
-  private pathPartsCache: Map<string, string[]> = new Map();
-  private pathJoinCache: Map<string, string> = new Map();
+  private pathManager: PathManager = new PathManager();
+  private visitedTracker: VisitedTracker = new VisitedTracker();
   private equivalencyDatabaseCache: Map<
     string,
     EquivalencyDatabaseEntry | undefined
@@ -187,7 +448,35 @@ export class ScopeDataStructure {
   // Inverted index: maps uniqueId -> EquivalencyDatabaseEntry for O(1) lookup
   private intermediatesOrderIndex: Map<string, EquivalencyDatabaseEntry> =
     new Map();
-  private globalVisited: Set<string> = new Set();
+
+  // Index for O(1) lookup of external function calls by name
+  // Invalidated by setting to null; rebuilt lazily on next access
+  private externalFunctionCallsIndex: Map<string, FunctionCallInfo> | null =
+    null;
+
+  // Tracks internal functions that have been filtered out during captureCompleteSchema
+  // Prevents re-adding them via subsequent equivalency propagation (e.g., from getReturnValue)
+  private filteredInternalFunctions: Set<string> = new Set();
+
+  // Debug tracer for selective path/scope tracing
+  // Enable via: CODEYAM_DEBUG=true CODEYAM_DEBUG_PATHS="user.*,signature" npm test
+  private tracer: DebugTracer = new DebugTracer({
+    enabled: process.env.CODEYAM_DEBUG === 'true',
+    pathPatterns: process.env.CODEYAM_DEBUG_PATHS
+      ? process.env.CODEYAM_DEBUG_PATHS.split(',').map((p) => new RegExp(p))
+      : [],
+    scopePatterns: process.env.CODEYAM_DEBUG_SCOPES
+      ? process.env.CODEYAM_DEBUG_SCOPES.split(',').map((p) => new RegExp(p))
+      : [],
+    maxDepth: 20,
+  });
+
+  // Batch processor for converting recursive addToSchema calls to iterative processing
+  // This eliminates deep recursion and allows for better work deduplication
+  private batchProcessor: BatchSchemaProcessor | null = null;
+  // Track items already in the batch queue to prevent duplicates
+  // For external function calls, uses path-only keys (no value) for more aggressive deduplication
+  private batchQueuedSet: Set<string> | null = null;
 
   constructor(
     managers: EquivalencyManager[],
@@ -196,7 +485,7 @@ export class ScopeDataStructure {
     scopeAnalysis: ScopeAnalysis,
   ) {
     this.equivalencyManagers.push(...managers);
-    this.scopeTree.name = scopeName;
+    this.scopeTreeManager.setRootName(scopeName);
     this.addScopeAnalysis(scopeName, scopeText, scopeAnalysis);
   }
 
@@ -208,8 +497,11 @@ export class ScopeDataStructure {
     isStatic?: boolean,
   ) {
     try {
-      if (scopeNodeName !== this.scopeTree.name && !parentScopeName) {
-        parentScopeName = this.scopeTree.name;
+      if (
+        scopeNodeName !== this.scopeTreeManager.getRootName() &&
+        !parentScopeName
+      ) {
+        parentScopeName = this.scopeTreeManager.getRootName();
       }
 
       let tree: any[] = [];
@@ -262,7 +554,7 @@ export class ScopeDataStructure {
         'CodeYam Error: Failed to add scope analysis for scope:',
         JSON.stringify(
           {
-            rootScopeName: this.scopeTree.name,
+            rootScopeName: this.scopeTreeManager.getRootName(),
             scopeNodeName,
             scopeNodeText: scopeText,
             isolatedStructure: scopeAnalysis.isolatedStructure,
@@ -277,97 +569,164 @@ export class ScopeDataStructure {
     }
   }
 
+  /**
+   * Phase 2: Build complete schemas by following all equivalencies.
+   *
+   * This is the main entry point for schema building. Call this after all
+   * scopes have been added via `addScopeAnalysis()`.
+   *
+   * ## What Happens
+   *
+   * 1. Resets state (visited tracker, schemas, database)
+   * 2. For each scope, follows equivalencies to build complete schemas
+   * 3. Filters out internal function calls (keeps only external-facing)
+   * 4. Propagates source/usage relationships for querying
+   *
+   * ## After Calling
+   *
+   * You can then use:
+   * - `getSchema()` - Get the built schema for a scope
+   * - `getSourceEquivalencies()` - Find where data comes from
+   * - `getUsageEquivalencies()` - Find where data is used
+   */
   async captureCompleteSchema() {
+    // Reset state for Phase 2
     this.onlyEquivalencies = false;
     this.equivalencyDatabase = [];
-    this.equivalencyDatabaseCache.clear(); // Clear cache when database is reset
-    this.intermediatesOrderIndex.clear(); // Clear inverted index when database is reset
-    this.globalVisited = new Set([]);
+    this.equivalencyDatabaseCache.clear();
+    this.intermediatesOrderIndex.clear();
+    this.visitedTracker.resetGlobalVisited();
 
     for (const externalFunctionCall of this.externalFunctionCalls) {
       externalFunctionCall.schema = {};
     }
 
-    // for (const scopeNode of Object.values(this.scopeNodes)) {
+    // Build schemas for all scopes in parallel
     await Promise.all(
       Object.values(this.scopeNodes).map(async (scopeNode) => {
         scopeNode.schema = {};
         await this.determineEquivalenciesAndBuildSchema(scopeNode);
       }),
     );
-    // }
+
     const validExternalFacingScopeNames = new Set<string>([
-      this.scopeTree.name,
+      this.scopeTreeManager.getRootName(),
     ]);
     this.externalFunctionCalls = this.externalFunctionCalls.filter((efc) => {
-      const efcName = efc.name.split('<')[0];
+      const efcName = this.pathManager.stripGenerics(efc.name);
       for (const manager of this.equivalencyManagers) {
         if (manager.internalFunctions.has(efcName)) {
+          // Track this so we don't re-add it via subsequent finalize calls
+          this.filteredInternalFunctions.add(efcName);
           return false;
         }
       }
       validExternalFacingScopeNames.add(efcName);
       return true;
     });
+    this.invalidateExternalFunctionCallsIndex();
+
+    // Pre-compute array methods list once (avoids Array.from() in hot loop)
+    const arrayMethodsList = Array.from(arrayMethodsSet);
+    const containsArrayMethod = (path: string) =>
+      arrayMethodsList.some((method) => path.includes(`.${method}(`));
 
     for (const entry of this.equivalencyDatabase) {
-      entry.usages = entry.usages.filter(
-        (usage) =>
-          validExternalFacingScopeNames.has(
-            usage.scopeNodeName.split('<')[0],
-          ) &&
+      entry.usages = entry.usages.filter((usage) => {
+        const baseName = this.pathManager.stripGenerics(usage.scopeNodeName);
+        return (
+          validExternalFacingScopeNames.has(baseName) &&
           (usage.schemaPath.startsWith('returnValue') ||
-            usage.schemaPath.startsWith(usage.scopeNodeName.split('<')[0])) &&
-          !Array.from(arrayMethodsSet).some((method) =>
-            usage.schemaPath.includes(`.${method}(`),
-          ),
-      );
-      entry.sourceCandidates = entry.sourceCandidates.filter(
-        (candidate) =>
-          validExternalFacingScopeNames.has(
-            candidate.scopeNodeName.split('<')[0],
-          ) &&
+            usage.schemaPath.startsWith(baseName)) &&
+          !containsArrayMethod(usage.schemaPath)
+        );
+      });
+      entry.sourceCandidates = entry.sourceCandidates.filter((candidate) => {
+        const baseName = this.pathManager.stripGenerics(
+          candidate.scopeNodeName,
+        );
+        // Check if this is a local variable path (doesn't contain function call pattern)
+        // Local variables like "surveys[]" or "items[]" are important for tracing data flow
+        // from parent to child components (e.g., surveys[] -> SurveyCard().signature[0].survey)
+        const isLocalVariablePath =
+          !candidate.schemaPath.includes('()') &&
+          !candidate.schemaPath.startsWith('signature[') &&
+          !candidate.schemaPath.startsWith('returnValue');
+
+        return (
+          validExternalFacingScopeNames.has(baseName) &&
           (candidate.schemaPath.startsWith('signature[') ||
-            candidate.schemaPath.startsWith(
-              candidate.scopeNodeName.split('<')[0],
-            )) &&
-          !Array.from(arrayMethodsSet).some((method) =>
-            candidate.schemaPath.includes(`.${method}(`),
-          ),
-      );
+            candidate.schemaPath.startsWith(baseName) ||
+            isLocalVariablePath) &&
+          !containsArrayMethod(candidate.schemaPath)
+        );
+      });
+
+      // If all sourceCandidates were filtered out (e.g., because they belonged to
+      // internal functions like useState), look for the highest-order intermediate
+      // that belongs to a valid external-facing scope
+      if (
+        entry.sourceCandidates.length === 0 &&
+        Object.keys(entry.intermediatesOrder).length > 0
+      ) {
+        // Find intermediates that belong to valid external-facing scopes
+        const validIntermediates = Object.entries(entry.intermediatesOrder)
+          .filter(([pathId]) => {
+            const [scopeNodeName, schemaPath] = pathId.split('::');
+            if (!scopeNodeName || !schemaPath) return false;
+            const baseName = this.pathManager.stripGenerics(scopeNodeName);
+            return (
+              validExternalFacingScopeNames.has(baseName) &&
+              !containsArrayMethod(schemaPath)
+            );
+          })
+          .sort((a, b) => b[1] - a[1]); // Sort by order descending (highest first)
+
+        if (validIntermediates.length > 0) {
+          const [pathId] = validIntermediates[0];
+          const [scopeNodeName, schemaPath] = pathId.split('::');
+          if (scopeNodeName && schemaPath) {
+            entry.sourceCandidates.push({ scopeNodeName, schemaPath });
+          }
+        }
+      }
     }
 
     this.propagateSourceAndUsageEquivalencies(
-      this.scopeNodes[this.scopeTree.name],
+      this.scopeNodes[this.scopeTreeManager.getRootName()],
     );
 
     for (const externalFunctionCall of this.externalFunctionCalls) {
-      const t = new Date().getTime();
-      // console.info("Start Propagating", JSON.stringify({
-      //   externalFunctionCallName: externalFunctionCall.name,
-      //   // sourceEquivalencies: externalFunctionCall.sourceEquivalencies,
-      // }, null, 2));
-
       this.propagateSourceAndUsageEquivalencies(externalFunctionCall);
-
-      const elapsedTime = new Date().getTime() - t;
-      if (elapsedTime > 100) {
-        console.warn('Long Propagation Time', {
-          externalFunctionCallName: externalFunctionCall.name,
-          time: elapsedTime,
-        });
-        // throw new Error("STOP - LONG PROPAGATION TIME")
-      }
-
-      // console.info("Done Propagating", JSON.stringify({
-      //   externalFunctionCallName: externalFunctionCall.name,
-      //   // sourceEquivalencies: externalFunctionCall.sourceEquivalencies,
-      //   // usageEquivalencies: externalFunctionCall.usageEquivalencies,
-      //   time: elapsedTime
-      // }, null, 2))
     }
   }
 
+  /**
+   * Core method: Adds a path/value to a scope's schema and follows equivalencies.
+   *
+   * This is the heart of schema building. For each path, it:
+   * 1. Validates the path and checks if already visited
+   * 2. Adds the path → value mapping to the scope's schema
+   * 3. Follows any equivalencies to propagate the schema to linked paths
+   * 4. Tracks the equivalency chain for source/usage database
+   *
+   * ## Cycle Detection
+   *
+   * Uses `visitedTracker.checkAndMarkGlobalVisited()` to prevent infinite loops.
+   * A path is considered visited if the exact (scope, path, value) tuple has
+   * been processed before.
+   *
+   * ## Equivalency Following
+   *
+   * When a path has equivalencies (e.g., `user` → `props.user`), this method
+   * recursively calls itself to add the equivalent path to its scope's schema.
+   *
+   * @param path - Schema path to add (e.g., 'user.id')
+   * @param value - Type value (e.g., 'string', 'number')
+   * @param scopeNode - The scope to add to
+   * @param equivalencyValueChain - Tracks the chain for database population
+   * @param traceId - Debug ID for tracing specific paths
+   */
   addToSchema({
     path,
     value,
@@ -382,11 +741,34 @@ export class ScopeDataStructure {
     traceId?: number;
   }) {
     addToSchemaCallCount++;
+
+    // Trace entry for debugging
+    this.tracer.traceEnter('addToSchema', {
+      path,
+      scope: scopeNode?.name,
+      value,
+      chainDepth: equivalencyValueChain.length,
+    });
+
+    // Safety: Detect runaway recursion
+    if (addToSchemaCallCount > 500000) {
+      console.error('INFINITE LOOP DETECTED in addToSchema', {
+        callCount: addToSchemaCallCount,
+        path,
+        value,
+        scopeNodeName: scopeNode?.name,
+      });
+      throw new Error(
+        `Infinite loop detected: addToSchema called ${addToSchemaCallCount} times`,
+      );
+    }
     // Track max chain depth
     if (equivalencyValueChain.length > maxEquivalencyChainDepth) {
       maxEquivalencyChainDepth = equivalencyValueChain.length;
     }
-    if (!scopeNode) return;
+    if (!scopeNode) {
+      return;
+    }
 
     if (!this.isValidPath(path)) {
       if (traceId) {
@@ -395,6 +777,7 @@ export class ScopeDataStructure {
       return;
     }
 
+    // Update chain metadata for database tracking
     if (equivalencyValueChain.length > 0) {
       equivalencyValueChain[equivalencyValueChain.length - 1].addToSchemaId =
         ++this.lastAddToSchemaId;
@@ -405,78 +788,18 @@ export class ScopeDataStructure {
       };
     }
 
-    // Use this debugging to track down an infinite loop
-    // traceId ||= 0;
-    // traceId += 1;
-    // if (traceId) {
-    //   console.info(JSON.stringify({ traceId, path, value, scopeNodeName: scopeNode.name }, null, 2));
-    // }
-    // if (traceId > 30) {
-    //   console.warn(
-    //     'HIGH TRACEID',
-    //     JSON.stringify(
-    //       {
-    //         path,
-    //         value,
-    //         scopeNodeName: scopeNode.name,
-    //         equivalencyValueChain,
-    //       },
-    //       null,
-    //       2,
-    //     ),
-    //   );
-    //   throw new Error('STOP - HIGH TRACEID');
-    // }
-
-    // Use this debugging to trace a specific path through the propagation
-    const debugLevel = 0; // 0 for minimal, 1 for executed paths, 2 for all paths info
-    // if ((!this.onlyEquivalencies && path === 'entity.sha') || traceId) {
-    //   traceId ||= 0;
-    //   traceId += 1;
-    //   if (traceId === 1) {
-    //     this.debugCount += 1;
-    //     if (this.debugCount > 5) throw new Error('STOP - HIGH DEBUG COUNT');
-    //     console.warn('START');
-    //   }
-
-    //   console.info(
-    //     'Debug Propagation: Adding to schema',
-    //     JSON.stringify(
-    //       {
-    //         // traceId,
-    //         path,
-    //         value,
-    //         scopeNodeName: scopeNode.name,
-    //         reason:
-    //           equivalencyValueChain[equivalencyValueChain.length - 1]?.reason,
-    //         // previous:
-    //         //   equivalencyValueChain[equivalencyValueChain.length - 1],
-    //         text: scopeNode.text,
-    //         // tree: scopeNode.tree,
-    //         // onlyEquivalencies: this.onlyEquivalencies,
-    //         // equivalencyValueChain,
-    //         // scopeNode
-    //         // instatiatedVeriables: scopeNode.instantiatedVariables,
-    //         // parentInstantiatedVariables: scopeNode.parentInstantiatedVariables,
-    //         // isolatedStructure: scopeNode.analysis.isolatedStructure,
-    //         // isolatedEquivalencies: scopeNode.analysis.isolatedEquivalentVariables,
-    //         // equivalencies: traceId === 1 ? scopeNode.equivalencies : 'skipped',
-    //         // functionCalls: scopeNode.functionCalls,
-    //         // externalFunctionCalls: this.externalFunctionCalls.filter(fc => fc.callScope.includes(scopeNode.name))
-    //       },
-    //       null,
-    //       2,
-    //     ),
-    //   );
-    //   // if (traceId > 1) traceId = undefined;
-    //   throw new Error('STOP ON ADD');
-    // }
+    // Debug level: 0=minimal, 1=executed paths, 2=all paths (set via traceId)
+    const debugLevel = 0;
 
+    // ─────────────────────────────────────────────────────────────────────────
+    // SECTION 1: Handle complex source paths (paths with multiple data origins)
+    // ─────────────────────────────────────────────────────────────────────────
     const equivalenciesDatabaseEntry = this.getEquivalenciesDatabaseEntry(
       scopeNode.name,
       path,
     );
 
+    // Process complex source paths (before visited check, per original design)
     this.addComplexSourcePathVariables(
       equivalenciesDatabaseEntry,
       scopeNode,
@@ -485,23 +808,19 @@ export class ScopeDataStructure {
       traceId,
     );
 
-    const uniqueIdentifier = `${scopeNode.name}::${path}::${value}`;
-
-    if (this.globalVisited.has(uniqueIdentifier)) {
+    // ─────────────────────────────────────────────────────────────────────────
+    // SECTION 2: Cycle detection - skip if already visited with this value
+    // ─────────────────────────────────────────────────────────────────────────
+    if (
+      this.visitedTracker.checkAndMarkGlobalVisited(scopeNode.name, path, value)
+    ) {
       if (traceId) {
-        console.info(
-          'Debug propagation: already globally visited path',
-          JSON.stringify(
-            {
-              uniqueIdentifier,
-              // equivalencyValueChain,
-            },
-            null,
-            2,
-          ),
-        );
+        console.info('Debug: already visited', {
+          key: `${scopeNode.name}::${path}::${value}`,
+        });
       }
 
+      // Still record in database even if visited (captures full chain)
       if (!this.onlyEquivalencies) {
         this.addToEquivalencyDatabase(equivalencyValueChain, traceId);
       }
@@ -509,8 +828,7 @@ export class ScopeDataStructure {
       return;
     }
 
-    this.globalVisited.add(uniqueIdentifier);
-
+    // Continue complex source processing after visited check
     this.captureComplexSourcePaths(
       equivalenciesDatabaseEntry,
       scopeNode,
@@ -519,6 +837,10 @@ export class ScopeDataStructure {
       traceId,
     );
 
+    // ─────────────────────────────────────────────────────────────────────────
+    // SECTION 3: Process each subpath to follow equivalencies
+    // For path "user.profile.name", processes: "user", "user.profile", "user.profile.name"
+    // ─────────────────────────────────────────────────────────────────────────
     const pathParts = this.splitPath(path);
 
     this.checkForArrayItemPath(pathParts, scopeNode, equivalencyValueChain);
@@ -637,6 +959,11 @@ export class ScopeDataStructure {
       }
     }
 
+    // ─────────────────────────────────────────────────────────────────────────
+    // SECTION 4: Write to schema if appropriate
+    // Only writes if: (a) path not set or is 'unknown', AND
+    //                 (b) path belongs to this scope (instantiated, signature, or return)
+    // ─────────────────────────────────────────────────────────────────────────
     const writeToCurrentScopeSchema =
       (!scopeNode.schema[path] || scopeNode.schema[path] === 'unknown') &&
       (!scopeNode.instantiatedVariables ||
@@ -644,50 +971,35 @@ export class ScopeDataStructure {
         pathParts[0].startsWith('signature[') ||
         pathParts[0].startsWith('returnValue'));
 
-    // Safe early exit: if we've already set this exact schema value, skip processing
+    // Early exit if schema already has this exact value
     if (scopeNode.schema[path] === value && value !== 'unknown') {
       return;
     }
 
     if (writeToCurrentScopeSchema) {
       if (traceId && debugLevel > 0) {
-        console.info('Debug Propagation: currentScope executed', {
-          traceId,
+        console.info('Debug: writing schema', {
           path,
-          pathParts,
-          scopeNodeName: scopeNode.name,
+          value,
+          scope: scopeNode.name,
         });
       }
       scopeNode.schema[path] = value;
     }
 
+    // ─────────────────────────────────────────────────────────────────────────
+    // SECTION 5: Record in equivalency database (Phase 2 only)
+    // ─────────────────────────────────────────────────────────────────────────
     if (!this.onlyEquivalencies) {
       this.addToEquivalencyDatabase(equivalencyValueChain, traceId);
     }
 
     if (traceId) {
-      console.info(
-        'Debug Propagation: exiting',
-        JSON.stringify(
-          {
-            traceId,
-            scopeNodeName: scopeNode.name,
-            path,
-            value,
-            // schemaValue: scopeNode.schema[path],
-            // propagated,
-            // scopeInfoText: scopeNode.text,
-            // equivalencyValueChain//: equivalencyValueChain.map(
-            //   (ev) => ev.currentPath.schemaPath,
-            // ),
-            // sourceEquivalencies: scopeNode.sourceEquivalencies[path] ?? [],
-            // usageEquivalencies: scopeNode.usageEquivalencies[path] ?? [],
-            // checkpoints,
-          },
-          null,
-          2,
-        ),
-      );
+      console.info('Debug: addToSchema complete', {
+        scope: scopeNode.name,
+        path,
+        value,
+      });
     }
   }
 
@@ -708,76 +1020,143 @@ export class ScopeDataStructure {
     equivalencyValueChain?: EquivalencyValueChainItem[],
     traceId?: number,
   ) {
-    // Temporary debugging to track down unnecessary equivalencies
-    if (
-      ![
-        'original equivalency',
-        'implicit parent equivalency',
-        'explicit parent equivalency',
-        'transformed non-object function equivalency - original equivalency',
-        'equivalency to external function call',
-        'functionCall to function signature equivalency', // 1 failure
-        'explicit parent signature',
-        'useState setter call equivalency',
-        'non-object function argument function signature equivalency1',
-        'non-object function argument function signature equivalency2',
-        'returnValue to functionCallReturnValue equivalency', // 2 failures
-        '.map() function deconstruction', // 1 failure
-        'useMemo return value equivalent to first argument return value',
-        'useState value equivalency', // 1 failure
-        'Node .then() equivalency', // 1 failure
-        'Explicit array deconstruction equivalency value', // 1 failure
-        'forwardRef equivalency',
-        'forwardRef signature to child signature equivalency', // 1 failure
-        'captured function call return value equivalency', // 1 failure (in ScopeDataStructure.test.ts)
-        'original equivalency - rerouted via useCallback', // 1 failure
-        'non-object function argument function signature equivalency1 - rerouted via useCallback', // 1 failure
-        'non-object function argument function signature equivalency2 - rerouted via useCallback', // 1 failure
-        'implicit parent equivalency - rerouted via useCallback', // 1 failure
-        'Spread operator equivalency key update: implicit parent equivalency', // 1 failure
-        'Array.from() equivalency',
-      ].includes(equivalencyReason)
-    ) {
-      if (
-        [
-          'signature of functionCall',
-          'transformed non-object function equivalency - implicit parent equivalency',
-          'transformed non-object function equivalency - non-object function argument function signature equivalency1',
-          'transformed non-object function equivalency - non-object function argument function signature equivalency2',
-          'transformed non-object function equivalency - equivalency to external function call',
-          'Explicit array deconstruction equivalency key',
-          'transformed non-object function equivalency - useState setter call equivalency',
-          'transformed non-object function equivalency - implicit parent equivalency - rerouted via useCallback',
-          'transformed non-object function equivalency - Array.from() equivalency',
-          'Spread operator equivalency key update: Explicit array deconstruction equivalency value',
-        ].includes(equivalencyReason)
-      ) {
+    addEquivalencyCallCount++;
+
+    if (addEquivalencyCallCount > 50000) {
+      console.error('INFINITE LOOP DETECTED in addEquivalency', {
+        callCount: addEquivalencyCallCount,
+        path,
+        equivalentPath,
+        equivalentScopeName,
+        scopeNodeName: scopeNode.name,
+        equivalencyReason,
+      });
+      throw new Error(
+        `Infinite loop detected: addEquivalency called ${addEquivalencyCallCount} times`,
+      );
+    }
+    // Filter equivalency reasons - use pre-computed Sets for O(1) lookup
+    if (!ALLOWED_EQUIVALENCY_REASONS.has(equivalencyReason)) {
+      if (SILENTLY_IGNORED_EQUIVALENCY_REASONS.has(equivalencyReason)) {
         return;
       } else {
+        // Log and skip - if an equivalency reason isn't in ALLOWED or SILENTLY_IGNORED,
+        // it shouldn't be stored (was previously missing the return)
         console.info('Not tracked equivalency reason', { equivalencyReason });
+        return;
+      }
+    }
+
+    // Skip self-referential equivalencies that would create infinite loops.
+    // Case 1: Direct self-reference (path === equivalentPath)
+    // FunctionCallManager adds equivalency(subPath, subPath, externalFunctionName, ...)
+    // For simple calls like buildBranchFileMap(), this is fine.
+    // But for chained calls like query.where().where().where(), each method call adds
+    // a .functionCallReturnValue segment, and the equivalency processing creates an infinite loop.
+    // We detect chained calls by counting .functionCallReturnValue occurrences in the path.
+    if (
+      path === equivalentPath &&
+      equivalencyReason === 'equivalency to external function call'
+    ) {
+      // Count how many .functionCallReturnValue segments are in the path
+      const functionCallReturnValueCount = (
+        path.match(/\.functionCallReturnValue/g) || []
+      ).length;
+      // Skip if there are multiple chained calls (2+ .functionCallReturnValue segments)
+      if (functionCallReturnValueCount >= 2) {
+        return;
       }
     }
 
+    // Case 2: Circular reference where equivalentPath contains path as a prefix
+    // e.g., path="query" and equivalentPath="query.where(...).functionCallReturnValue"
+    // This happens with method chaining patterns where a variable is reassigned to
+    // the result of a method call on itself: query = query.where(...)
+    // Resolving this equivalency would require resolving query first, creating infinite recursion.
+    if (
+      equivalentPath.startsWith(path + '.') ||
+      equivalentPath.startsWith(path + '(')
+    ) {
+      return;
+    }
+
     if (!equivalentScopeName) {
-      console.warn('Debug Propagation: missing equivalent scope name', {
-        path,
-        equivalentPath,
-        equivalentScopeName,
-        scopeNodeName: scopeNode.name,
-      });
+      console.error(
+        'CodeYam Error: Missing equivalent scope name - FULL CONTEXT:',
+        JSON.stringify(
+          {
+            path,
+            equivalentPath,
+            equivalentScopeName,
+            scopeNodeName: scopeNode.name,
+            equivalencyReason,
+            tree: scopeNode.tree,
+            equivalencyValueChain: equivalencyValueChain?.map((ev) => ({
+              id: ev.id,
+              source: ev.source,
+              reason: ev.reason,
+              currentPath: ev.currentPath,
+              previousPath: ev.previousPath,
+            })),
+            scopeNodeFunctionCalls: scopeNode.functionCalls?.map((fc) => ({
+              name: fc.name,
+              callSignature: fc.callSignature,
+              callScope: fc.callScope,
+            })),
+            instantiatedVariables: scopeNode.instantiatedVariables,
+            parentInstantiatedVariables: scopeNode.parentInstantiatedVariables,
+          },
+          null,
+          2,
+        ),
+      );
       throw new Error('CodeYam Error: Missing equivalent scope name');
     }
 
     scopeNode.equivalencies[path] ||= [];
 
     const existing = scopeNode.equivalencies[path];
-    if (
-      existing.find(
-        (v) =>
-          v.schemaPath === equivalentPath &&
-          v.scopeNodeName === equivalentScopeName,
-      )
-    ) {
+    const existingEquivalency = existing.find(
+      (v) =>
+        v.schemaPath === equivalentPath &&
+        v.scopeNodeName === equivalentScopeName,
+    );
+    if (existingEquivalency) {
+      // During Phase 2 (onlyEquivalencies=false), we need to still process the equivalency
+      // to build the chain and add to the database, even if the equivalency already exists
+      if (!this.onlyEquivalencies) {
+        const equivalentScopeNode = this.getScopeOrFunctionCallInfo(
+          equivalentScopeName,
+        ) as ScopeNode;
+        if (equivalentScopeNode) {
+          // Extract function call name from path if it looks like a function call path
+          // e.g., "ChildComponent().signature[0].dataItem" -> "ChildComponent"
+          const pathMatch = path.match(/^([^().]+)\(\)/);
+          const previousPathScopeNodeName = pathMatch
+            ? pathMatch[1]
+            : scopeNode.name;
+
+          this.addToSchema({
+            path: equivalentPath,
+            value: 'unknown',
+            scopeNode: equivalentScopeNode,
+            equivalencyValueChain: [
+              ...(equivalencyValueChain ?? []),
+              {
+                id: existingEquivalency.id,
+                source: 'duplicate equivalency - Phase 2',
+                reason: equivalencyReason,
+                previousPath: {
+                  scopeNodeName: previousPathScopeNodeName,
+                  schemaPath: path,
+                  value: scopeNode.schema[path],
+                },
+              },
+            ],
+            traceId,
+          });
+        }
+      }
       return;
     }
 
@@ -884,19 +1263,63 @@ export class ScopeDataStructure {
         functionCallInfo.equivalencies = {};
       }
 
-      const existingFunctionCall = this.externalFunctionCalls.find(
-        (fc) => getFunctionCallRoot(functionCallInfo.callSignature) === fc.name,
-      );
+      const searchKey = getFunctionCallRoot(functionCallInfo.callSignature);
+      const existingFunctionCall =
+        this.getExternalFunctionCallsIndex().get(searchKey);
       if (existingFunctionCall) {
-        existingFunctionCall.schema = {
+        // Preserve per-call schemas BEFORE merging to enable per-variable mock data.
+        // This is critical for hooks like useFetcher<UserData>() vs useFetcher<ReportData>()
+        // where each call returns different typed data.
+        if (!existingFunctionCall.perCallSignatureSchemas) {
+          // First merge - save the existing call's schema
+          existingFunctionCall.perCallSignatureSchemas = {
+            [existingFunctionCall.callSignature]: {
+              ...existingFunctionCall.schema,
+            },
+          };
+        }
+        // Save the new call's schema before it gets merged
+        existingFunctionCall.perCallSignatureSchemas[
+          functionCallInfo.callSignature
+        ] = { ...functionCallInfo.schema };
+
+        // Merge schemas using selectBestValue to preserve specific types like 'null'
+        // over generic types like 'unknown'. This ensures ref variables detected
+        // earlier (marked as 'null') aren't overwritten by later 'unknown' values.
+        const mergedSchema: Record<string, string> = {
           ...existingFunctionCall.schema,
-          ...functionCallInfo.schema,
         };
+        for (const key in functionCallInfo.schema) {
+          const existingValue = existingFunctionCall.schema[key];
+          const newValue = functionCallInfo.schema[key];
+          mergedSchema[key] = selectBestValue(
+            existingValue,
+            newValue,
+            newValue,
+          );
+        }
+        existingFunctionCall.schema = mergedSchema;
 
         existingFunctionCall.equivalencies = {
           ...existingFunctionCall.equivalencies,
           ...functionCallInfo.equivalencies,
         };
+
+        // Track all call signatures that get merged (e.g., logger.info, logger.debug, etc.)
+        if (!existingFunctionCall.allCallSignatures) {
+          existingFunctionCall.allCallSignatures = [
+            existingFunctionCall.callSignature,
+          ];
+        }
+        if (
+          !existingFunctionCall.allCallSignatures.includes(
+            functionCallInfo.callSignature,
+          )
+        ) {
+          existingFunctionCall.allCallSignatures.push(
+            functionCallInfo.callSignature,
+          );
+        }
       } else {
         const functionCallInfoNameParts = this.splitPath(functionCallInfo.name);
         const isExternal =
@@ -908,7 +1331,15 @@ export class ScopeDataStructure {
           );
 
         if (isExternal) {
-          this.externalFunctionCalls.push(functionCallInfo);
+          // Check if this function was already filtered out as an internal function
+          // (e.g., useState was filtered in captureCompleteSchema but finalize is trying to re-add it)
+          const strippedName = this.pathManager.stripGenerics(
+            functionCallInfo.name,
+          );
+          if (!this.filteredInternalFunctions.has(strippedName)) {
+            this.externalFunctionCalls.push(functionCallInfo);
+            this.invalidateExternalFunctionCallsIndex();
+          }
         }
       }
     }
@@ -935,7 +1366,7 @@ export class ScopeDataStructure {
     // }
 
     const getRootOrExternalFunctionCallInfo = (name: string) => {
-      return name === this.scopeTree.name
+      return name === this.scopeTreeManager.getRootName()
         ? this.getScopeNode()
         : this.getExternalFunctionCallInfo(name);
     };
@@ -966,6 +1397,40 @@ export class ScopeDataStructure {
         },
       );
 
+      // PERF: Build a Map for O(1) lookup instead of O(n) inner loop
+      // Map from "remaining parts joined" to equivalentSchemaPath
+      const equivalentSchemaPathMap = new Map<string, string>();
+      for (const equivalentSchemaPath of Object.keys(
+        equivalentScopeNode.schema,
+      )) {
+        // Quick string check before expensive path splitting
+        if (
+          !(
+            equivalentSchemaPath.startsWith(equivalentPath) ||
+            equivalentSchemaPath === equivalentPath ||
+            equivalentPath.startsWith(equivalentSchemaPath)
+          )
+        ) {
+          continue;
+        }
+
+        const equivalentSchemaPathParts = this.splitPath(equivalentSchemaPath);
+
+        if (
+          !equivalentPathParts.every(
+            (p, i) => equivalentSchemaPathParts[i] === p,
+          )
+        ) {
+          continue;
+        }
+
+        const remainingEquivalentSchemaPathParts =
+          equivalentSchemaPathParts.slice(equivalentPathParts.length);
+        // Use | as separator since it won't appear in path parts
+        const key = remainingEquivalentSchemaPathParts.join('|');
+        equivalentSchemaPathMap.set(key, equivalentSchemaPath);
+      }
+
       for (const schemaPath of relevantSchemaPaths) {
         const schemaPathParts = this.splitPath(schemaPath);
 
@@ -977,106 +1442,41 @@ export class ScopeDataStructure {
           pathParts.length,
         );
 
-        let missingEquivalentPath = false;
-
-        // Performance optimization: pre-filter equivalent schema paths
-        const relevantEquivalentSchemaPaths = Object.keys(
-          equivalentScopeNode.schema,
-        ).filter((equivalentSchemaPath) => {
-          // Quick string check before expensive path splitting
-          return (
-            equivalentSchemaPath.startsWith(equivalentPath) ||
-            equivalentSchemaPath === equivalentPath ||
-            equivalentPath.startsWith(equivalentSchemaPath)
-          );
-        });
-
-        for (const equivalentSchemaPath of relevantEquivalentSchemaPaths) {
-          const equivalentSchemaPathParts =
-            this.splitPath(equivalentSchemaPath);
-
-          if (
-            !equivalentPathParts.every(
-              (p, i) => equivalentSchemaPathParts[i] === p,
-            )
-          ) {
-            continue;
-          }
-
-          const remainingEquivalentSchemaPathParts =
-            equivalentSchemaPathParts.slice(equivalentPathParts.length);
-
-          if (
-            remainingSchemaPathParts.length !==
-              remainingEquivalentSchemaPathParts.length ||
-            !remainingEquivalentSchemaPathParts.every(
-              (p, i) => p === remainingSchemaPathParts[i],
-            )
-          ) {
-            missingEquivalentPath = true;
-            continue;
-          }
-          missingEquivalentPath = false;
+        // PERF: O(1) Map lookup instead of O(n) inner loop
+        const remainingKey = remainingSchemaPathParts.join('|');
+        const equivalentSchemaPath = equivalentSchemaPathMap.get(remainingKey);
+
+        if (equivalentSchemaPath) {
+          // Skip propagation when there's a structural mismatch:
+          // - schemaPath ends with [] (array element, represents an object)
+          // - equivalentSchemaPath doesn't end with [] (non-array prop, usually a scalar)
+          // This prevents incorrectly typing array elements as strings when they're
+          // equivalent to scalar props like JSX keys (e.g., workouts[] ↔ Card().key)
+          const schemaPathEndsWithArray = schemaPath.endsWith('[]');
+          const equivalentEndsWithArray = equivalentSchemaPath.endsWith('[]');
+          if (schemaPathEndsWithArray !== equivalentEndsWithArray) {
+            // Don't propagate between array element paths and non-array paths
+            continue;
+          }
 
           const value1 = scopeNode.schema[schemaPath];
           const value2 = equivalentScopeNode.schema[equivalentSchemaPath];
 
-          let bestValue = value1 ?? value2 ?? 'unknown';
-          if (
-            value2 &&
-            ((bestValue === 'unknown' && value2 !== 'unknown') ||
-              (bestValue.includes('unknown') && !value2.includes('unknown')))
-          ) {
-            bestValue = value2;
-          }
+          const bestValue = selectBestValue(value1, value2);
 
           scopeNode.schema[schemaPath] = bestValue;
           equivalentScopeNode.schema[equivalentSchemaPath] = bestValue;
-
-          // if (traceId) {
-          //   console.info('Debug Propagate: Assign Best Value', {
-          //     traceId,
-          //     sourceScopeNodeName: scopeNode.name,
-          //     path,
-          //     schemaPath,
-          //     usageScopeNodeName: equivalentScopeNode.name,
-          //     equivalentPath,
-          //     equivalentSchemaPath,
-          //     remainingSchemaPathParts,
-          //     remainingEquivalentSchemaPathParts,
-          //     value1,
-          //     value2,
-          //     bestValue,
-          //   });
-          // }
-          break;
-        }
-
-        if (
-          missingEquivalentPath &&
-          (scopeNode.name.includes('____cyScope') ||
-            !('instantiatedVariables' in equivalentScopeNode))
+        } else if (
+          scopeNode.name.includes('____cyScope') ||
+          !('instantiatedVariables' in equivalentScopeNode)
         ) {
+          // No matching equivalent path found - create one if needed
           // Only necessary for internal function scopes or external function scopes
           const newEquivalentPath = this.joinPathParts([
             equivalentPath,
             ...remainingSchemaPathParts,
           ]);
 
-          // if (traceId) {
-          //   console.info('Debug Propagate: missing equivalent path', {
-          //     traceId,
-          //     scopeNodeName: scopeNode.name,
-          //     path,
-          //     equivalentPath,
-          //     schemaPath,
-          //     remainingSchemaPathParts,
-          //     equivalentScopeNodeName: equivalentScopeNode.name,
-          //     // equivalentScopeNodeSchema: equivalentScopeNode.schema,
-          //     newEquivalentPath,
-          //   });
-          // }
-
           equivalentScopeNode.schema[newEquivalentPath] =
             scopeNode.schema[schemaPath];
         }
@@ -1118,111 +1518,111 @@ export class ScopeDataStructure {
     }
   }
 
-  splitPath(path: string): string[] {
-    if (this.pathPartsCache.has(path)) {
-      return structuredClone(this.pathPartsCache.get(path)!);
-    }
-    const pathParts = splitOutsideParenthesesAndArrays(path);
-    this.pathPartsCache.set(path, structuredClone(pathParts));
-    return pathParts;
+  splitPath(path: string): readonly string[] {
+    return this.pathManager.splitPath(path);
   }
 
-  joinPathParts(pathParts: string[]): string {
-    const cacheKey = pathParts.join('|');
-    if (this.pathJoinCache.has(cacheKey)) {
-      return this.pathJoinCache.get(cacheKey)!;
+  joinPathParts(pathParts: readonly string[]): string {
+    return this.pathManager.joinPathParts(pathParts);
+  }
+
+  /**
+   * Extracts the root variable name from a path.
+   * E.g., "collected[]" -> "collected", "foo.bar" -> "foo", "collected[0]" -> "collected"
+   */
+  extractRootVariable(path: string): string | null {
+    const parts = this.splitPath(path);
+    if (parts.length === 0) return null;
+
+    const firstPart = parts[0];
+    // Strip array notation: "collected[]" -> "collected", "collected[0]" -> "collected"
+    const bracketIndex = firstPart.indexOf('[');
+    if (bracketIndex > 0) {
+      return firstPart.substring(0, bracketIndex);
     }
-    const result = joinParenthesesAndArrays(pathParts);
-    this.pathJoinCache.set(cacheKey, result);
-    return result;
+    return firstPart;
   }
 
   // PRIVATE METHODS //
 
-  private uniqueId({
-    scopeNodeName,
-    schemaPath,
-    value,
-  }: {
+  private uniqueId(params: {
     scopeNodeName: string;
     schemaPath: string;
     value?: string;
   }): string {
-    const parts = [scopeNodeName, schemaPath, value].filter(Boolean);
-    return parts.join('::');
+    return uniqueId(params);
   }
 
   private uniqueScopeVariables(scopeVariables: ScopeVariable[]) {
-    return this.uniqueScopeAndPaths(scopeVariables) as ScopeVariable[];
+    return uniqueScopeVariables(scopeVariables);
   }
 
   private uniqueScopeAndPaths(
     scopeVariables: Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[],
   ) {
-    if (!scopeVariables || scopeVariables.length === 0) return [];
-
-    // Optimize from O(n²) to O(n) using Set for deduplication
-    const seen = new Set<string>();
-    return scopeVariables.filter((varItem) => {
-      const key = `${varItem.scopeNodeName}::${varItem.schemaPath}`;
-      if (seen.has(key)) {
-        return false;
-      }
-      seen.add(key);
-      return true;
-    });
+    return uniqueScopeAndPaths(scopeVariables);
   }
 
   private isValidPath(path: string): boolean {
-    if (typeof path !== 'string') {
-      return false;
-    }
+    return this.pathManager.isValidPath(path);
+  }
 
-    if (!path) {
-      return false;
+  /**
+   * Detects if a path contains excessive repetition of the same pattern.
+   *
+   * This prevents exponential blowup when analyzing recursive type structures.
+   * For example, TypeScript AST nodes have `.attributes.properties[]` where each
+   * property is also a node with `.attributes.properties[]`. Without this check,
+   * paths like `signature[0].attributes.properties[].attributes.properties[].attributes.properties[]...`
+   * would be generated exponentially.
+   *
+   * Two detection strategies:
+   * 1. Known patterns: Check RECURSIVE_PATH_PATTERNS for common recursive structures
+   * 2. Generic detection: For longer paths, detect any 2-3 part segment that repeats
+   *
+   * @param path - The schema path to check
+   * @param maxRepetitions - Maximum allowed repetitions of any pattern (default: 2)
+   * @returns true if the path has excessive repetition
+   */
+  private hasExcessivePatternRepetition(
+    path: string,
+    maxRepetitions = 2,
+  ): boolean {
+    // Check known recursive patterns
+    for (const pattern of RECURSIVE_PATH_PATTERNS) {
+      const matches = path.match(pattern);
+      if (matches && matches.length > maxRepetitions) {
+        return true;
+      }
     }
 
-    if (path === 'true' || path === 'false') {
+    // For longer paths, detect any repeated multi-part segments we haven't explicitly listed
+    const pathParts = this.splitPath(path);
+    if (pathParts.length <= 6) {
       return false;
     }
 
-    if (!isNaN(Number(path))) {
-      return false;
-    }
+    // Check for repeated sequences of 2-3 consecutive parts
+    for (let segmentLength = 2; segmentLength <= 3; segmentLength++) {
+      const seen = new Map<string, number>();
 
-    if (path.match(/^['"]/)) {
-      return false;
-    }
+      for (let i = 0; i <= pathParts.length - segmentLength; i++) {
+        const segment = pathParts.slice(i, i + segmentLength).join('.');
+        const normalizedSegment = segment.replace(/\[\d+\]/g, '[]');
+        const count = (seen.get(normalizedSegment) || 0) + 1;
+        seen.set(normalizedSegment, count);
 
-    return this.splitPath(path).every((part) => {
-      if (
-        cleanOutBoundary(
-          cleanOutBoundary(cleanOutBoundary(part, '<', '>'), '[', ']'),
-        ).match(/\s/)
-      ) {
-        return false;
+        if (count > maxRepetitions) {
+          return true;
+        }
       }
-      return true;
-    });
+    }
+
+    return false;
   }
 
   private addToTree(pathParts: string[]) {
-    let scopeTreeNode = { children: [this.scopeTree] };
-    for (const pathPart of pathParts) {
-      const existingChild = scopeTreeNode.children.find(
-        (child) => child.name === pathPart,
-      );
-      if (existingChild) {
-        scopeTreeNode = existingChild;
-      } else {
-        const childScopeTreeNode = {
-          name: pathPart,
-          children: [] as any[],
-        };
-        scopeTreeNode.children.push(childScopeTreeNode);
-        scopeTreeNode = childScopeTreeNode;
-      }
-    }
+    this.scopeTreeManager.addPath(pathParts);
   }
 
   private setInstantiatedVariables(scopeNode: ScopeNode) {
@@ -1289,6 +1689,10 @@ export class ScopeDataStructure {
   }
 
   private determineEquivalenciesAndBuildSchema(scopeNode: ScopeNode) {
+    if (!scopeNode.analysis) {
+      return;
+    }
+
     const { isolatedStructure, isolatedEquivalentVariables } =
       scopeNode.analysis;
 
@@ -1304,11 +1708,24 @@ export class ScopeDataStructure {
       let equivalentValue = isolatedEquivalentVariables?.[path];
 
       if (equivalentValue && this.isValidPath(equivalentValue)) {
-        path = cleanPath(path.replace(/::cyDuplicateKey\d+::/g, ''), allPaths);
-        equivalentValue = cleanPath(
-          equivalentValue.replace(/::cyDuplicateKey\d+::/g, ''),
-          allPaths,
-        );
+        // IMPORTANT: DO NOT strip ::cyDuplicateKey:: markers from equivalencies.
+        // These markers are critical for distinguishing variable reassignments.
+        // For example, with:
+        //   let fetcher = useFetcher<ConfigData>();
+        //   const configData = fetcher.data?.data;
+        //   fetcher = useFetcher<SettingsData>();
+        //   const settingsData = fetcher.data?.data;
+        //
+        // mergeStatements creates:
+        //   fetcher → useFetcher<ConfigData>()...
+        //   fetcher::cyDuplicateKey1:: → useFetcher<SettingsData>()...
+        //   configData → fetcher.data.data
+        //   settingsData → fetcher::cyDuplicateKey1::.data.data
+        //
+        // If we strip ::cyDuplicateKey::, settingsData would incorrectly trace
+        // to useFetcher<ConfigData>() instead of useFetcher<SettingsData>().
+        path = cleanPath(path, allPaths);
+        equivalentValue = cleanPath(equivalentValue, allPaths);
 
         this.addEquivalency(
           path,
@@ -1317,17 +1734,150 @@ export class ScopeDataStructure {
           scopeNode,
           'original equivalency',
         );
+
+        // Propagate equivalencies involving parent-scope variables to those parent scopes.
+        // This handles patterns like: collected.push({...entity}) where 'collected' is defined
+        // in a parent scope. The equivalency collected[] -> push().signature[0] needs to be
+        // visible when tracing from the parent scope.
+        const rootVariable = this.extractRootVariable(path);
+        const equivalentRootVariable =
+          this.extractRootVariable(equivalentValue);
+
+        // Skip propagation for self-referential reassignment patterns like:
+        //   x = x.method().functionCallReturnValue
+        // where the path IS the variable itself (not a sub-path like x[] or x.prop).
+        // These create circular references since both sides reference the same variable.
+        //
+        // But DO propagate for patterns like collected[] -> collected.push(...).signature[0]
+        // where the path has additional segments beyond the root variable.
+        const pathIsJustRootVariable = path === rootVariable;
+        const isSelfReferentialReassignment =
+          pathIsJustRootVariable && rootVariable === equivalentRootVariable;
+
+        if (
+          rootVariable &&
+          !isSelfReferentialReassignment &&
+          scopeNode.parentInstantiatedVariables?.includes(rootVariable)
+        ) {
+          // Find the parent scope where this variable is defined
+          for (const parentScopeName of scopeNode.tree || []) {
+            const parentScope = this.scopeNodes[parentScopeName];
+            if (parentScope?.instantiatedVariables?.includes(rootVariable)) {
+              // Add the equivalency to the parent scope as well
+              this.addEquivalency(
+                path,
+                equivalentValue,
+                scopeNode.name, // The equivalent path's scope remains the child scope
+                parentScope, // But store it in the parent scope's equivalencies
+                'propagated parent-variable equivalency',
+              );
+              break;
+            }
+          }
+        }
+
+        // Propagate sub-property equivalencies when the equivalentValue is a simple variable
+        // that has sub-properties defined in the isolatedEquivalentVariables.
+        // This handles cases like: dataItem={{ structure: completeDataStructure }}
+        // where completeDataStructure has sub-properties like completeDataStructure['Function Arguments']
+        // We need to propagate these to create: dataItem.structure['Function Arguments'] equivalencies
+        const isSimpleVariable =
+          !equivalentValue.startsWith('signature[') &&
+          !equivalentValue.includes('functionCallReturnValue') &&
+          !equivalentValue.includes('.') &&
+          !equivalentValue.includes('[');
+
+        if (isSimpleVariable) {
+          // Look in current scope and all parent scopes for sub-properties
+          const scopesToCheck = [scopeNode.name, ...scopeNode.tree];
+          for (const scopeName of scopesToCheck) {
+            const checkScope = this.scopeNodes[scopeName];
+            if (!checkScope?.analysis?.isolatedEquivalentVariables) continue;
+
+            for (const [subPath, subValue] of Object.entries(
+              checkScope.analysis.isolatedEquivalentVariables,
+            )) {
+              // Check if this is a sub-property of the equivalentValue variable
+              // e.g., completeDataStructure['Function Arguments'] or completeDataStructure.foo
+              const matchesDot = subPath.startsWith(equivalentValue + '.');
+              const matchesBracket = subPath.startsWith(equivalentValue + '[');
+              if (matchesDot || matchesBracket) {
+                const subPropertyPath = subPath.substring(
+                  equivalentValue.length,
+                );
+                const newPath = cleanPath(path + subPropertyPath, allPaths);
+                const newEquivalentValue = cleanPath(
+                  (subValue as string).replace(/::cyDuplicateKey\d+::/g, ''),
+                  allPaths,
+                );
+
+                if (
+                  newEquivalentValue &&
+                  this.isValidPath(newEquivalentValue)
+                ) {
+                  this.addEquivalency(
+                    newPath,
+                    newEquivalentValue,
+                    checkScope.name, // Use the scope where the sub-property was found
+                    scopeNode,
+                    'propagated sub-property equivalency',
+                  );
+                }
+              }
+
+              // Also check if equivalentValue itself maps to a functionCallReturnValue
+              // e.g., result = useMemo(...).functionCallReturnValue
+              if (
+                subPath === equivalentValue &&
+                typeof subValue === 'string' &&
+                subValue.endsWith('.functionCallReturnValue')
+              ) {
+                this.propagateFunctionCallReturnSubProperties(
+                  path,
+                  subValue,
+                  scopeNode,
+                  allPaths,
+                );
+              }
+            }
+          }
+        }
+
+        // Handle function call return values by propagating returnValue.* sub-properties
+        // from the callback scope to the usage path
+        if (equivalentValue.endsWith('.functionCallReturnValue')) {
+          this.propagateFunctionCallReturnSubProperties(
+            path,
+            equivalentValue,
+            scopeNode,
+            allPaths,
+          );
+
+          // Track which variable receives the return value of each function call
+          // This enables generating separate mock data for each call site
+          this.trackReceivingVariable(path, equivalentValue);
+        }
+
+        // Also track variables that receive destructured properties from function call return values
+        // e.g., "userData" -> "db.query('users').functionCallReturnValue.data"
+        if (equivalentValue.includes('.functionCallReturnValue.')) {
+          this.trackReceivingVariable(path, equivalentValue);
+        }
       }
     }
 
-    for (const key of Array.from(allPaths)) {
+    // PERF: Enable batch processing to convert recursive addToSchema calls to iterative
+    // This eliminates deep call stacks and improves deduplication
+    this.batchProcessor = new BatchSchemaProcessor();
+    this.batchQueuedSet = new Set();
+
+    for (const key of allPaths) {
       let value = isolatedStructure[key] ?? 'unknown';
 
       if (['null', 'undefined'].includes(value)) {
         value = 'unknown';
       }
 
-      const startTime = new Date().getTime();
       this.addToSchema({
         path: cleanPath(key, allPaths),
         value,
@@ -1341,31 +1891,380 @@ export class ScopeDataStructure {
         ],
       });
 
-      // const timeDiff = new Date().getTime() - startTime;
-      // if (timeDiff / 1000 > 1) {
-      //   console.info('SLOW', {
-      //     timeDiff,
-      //     root: this.scopeTree.name,
-      //     scopeNodeName: scopeNode.name,
-      //     schemaPath: key,
-      //     onlyEquivalencies: this.onlyEquivalencies,
-      //   });
-      // }
+      // Process any work queued by followEquivalencies
+      this.processBatchQueue();
     }
 
+    // Final pass to ensure all queued work is processed
+    this.processBatchQueue();
+
+    // Clean up batch processor
+    this.batchProcessor = null;
+    this.batchQueuedSet = null;
+
     this.validateSchema(scopeNode, false, false);
   }
 
+  /**
+   * Process all items in the batch queue.
+   * Each item may queue more work via followEquivalencies.
+   */
+  private processBatchQueue(): void {
+    if (!this.batchProcessor) return;
+
+    let iterations = 0;
+
+    while (this.batchProcessor.hasWork()) {
+      iterations++;
+
+      // Safety: detect potential infinite loops
+      if (iterations > 100000) {
+        console.error(
+          `[ScopeDataStructure] processBatchQueue exceeded 100k iterations, possible infinite loop!`,
+        );
+        break;
+      }
+
+      const item = this.batchProcessor.getNextWork();
+      if (!item) break;
+
+      const scopeNode = this.getScopeOrFunctionCallInfo(
+        item.scopeNodeName,
+      ) as ScopeNode;
+      if (!scopeNode) continue;
+
+      this.addToSchema({
+        path: item.path,
+        value: item.value,
+        scopeNode,
+        equivalencyValueChain:
+          item.equivalencyValueChain as EquivalencyValueChainItem[],
+        traceId: item.traceId,
+      });
+    }
+  }
+
+  /**
+   * Tracks which variable receives the return value of a function call.
+   *
+   * When we encounter an equivalency like:
+   *   result1 -> db.select(query1).functionCallReturnValue
+   *
+   * This method extracts the call signature (db.select(query1)) and maps it
+   * to the receiving variable (result1) on the corresponding FunctionCallInfo.
+   *
+   * This enables generating separate mock data for each call site when the same
+   * function is called multiple times with different arguments.
+   */
+  private trackReceivingVariable(
+    receivingVariable: string,
+    equivalentValue: string,
+  ): void {
+    // Extract the call signature by finding the .functionCallReturnValue part
+    // and taking everything before it
+    // Handles both:
+    //   "db.select(query1).functionCallReturnValue" -> "db.select(query1)"
+    //   "db.query('users').functionCallReturnValue.data" -> "db.query('users')"
+    const funcReturnIdx = equivalentValue.indexOf('.functionCallReturnValue');
+    if (funcReturnIdx === -1) {
+      return;
+    }
+    const callSignature = equivalentValue.substring(0, funcReturnIdx);
+
+    // Skip if the receiving variable is not a simple identifier
+    // (e.g., skip if it's a path like "obj.property" or contains array access)
+    if (receivingVariable.includes('.') || receivingVariable.includes('[')) {
+      return;
+    }
+
+    // Find the FunctionCallInfo that matches this call signature
+    const searchKey = getFunctionCallRoot(callSignature);
+    const functionCallInfo =
+      this.getExternalFunctionCallsIndex().get(searchKey);
+
+    if (!functionCallInfo) {
+      return;
+    }
+
+    // Initialize arrays if needed
+    if (!functionCallInfo.receivingVariableNames) {
+      functionCallInfo.receivingVariableNames = [];
+    }
+    if (!functionCallInfo.callSignatureToVariable) {
+      functionCallInfo.callSignatureToVariable = {};
+    }
+
+    // Add the receiving variable to the list (if not already present)
+    if (!functionCallInfo.receivingVariableNames.includes(receivingVariable)) {
+      functionCallInfo.receivingVariableNames.push(receivingVariable);
+    }
+
+    // Map the call signature to its receiving variable
+    // Use the full call signature (not the search key) for precise mapping
+    functionCallInfo.callSignatureToVariable[callSignature] = receivingVariable;
+  }
+
+  /**
+   * Propagates returnValue.* sub-properties from a callback scope to the usage path.
+   *
+   * When we have an equivalency like:
+   *   DataItemEditor().signature[0].structure -> getData().functionCallReturnValue
+   *
+   * And the callback scope for getData has:
+   *   returnValue.args -> dataStructure.arguments
+   *
+   * This method creates the transitive equivalency:
+   *   DataItemEditor().signature[0].structure.args -> signature[0].dataStructure.arguments
+   *
+   * It also resolves variable references through parent scopes (e.g., dataStructure -> signature[0].dataStructure)
+   * and ensures the database entry is updated with the usage path.
+   */
+  private propagateFunctionCallReturnSubProperties(
+    path: string,
+    equivalentValue: string,
+    scopeNode: ScopeNode,
+    allPaths: string[],
+  ) {
+    // Try to find the callback scope name from different patterns:
+    // 1. "getData().functionCallReturnValue" → look up getData variable to find scope
+    // 2. "useMemo(cyScope1(), [...]).functionCallReturnValue" → extract cyScope1 directly
+    let callbackScopeName: string | undefined;
+
+    // Pattern 1: Simple function call like getData().functionCallReturnValue
+    const simpleFunctionMatch = equivalentValue.match(
+      /^(\w+)\(\)\.functionCallReturnValue$/,
+    );
+    if (simpleFunctionMatch) {
+      const functionName = simpleFunctionMatch[1];
+      // Find the function reference in current or parent scopes
+      const scopesToCheck = [scopeNode.name, ...scopeNode.tree];
+      for (const scopeName of scopesToCheck) {
+        const checkScope = this.scopeNodes[scopeName];
+        if (!checkScope?.analysis?.isolatedEquivalentVariables) continue;
+
+        const functionRef =
+          checkScope.analysis.isolatedEquivalentVariables[functionName];
+        if (typeof functionRef === 'string' && functionRef.endsWith('F')) {
+          callbackScopeName = functionRef.slice(0, -1);
+          break;
+        }
+      }
+    }
+
+    // Pattern 2: useMemo/useCallback with callback scope
+    // e.g., "useMemo(cyScope1(), [deps]).functionCallReturnValue"
+    if (!callbackScopeName) {
+      const useMemoMatch = equivalentValue.match(
+        /^useMemo\((\w+)\(\),\s*\[.*\]\)\.functionCallReturnValue$/,
+      );
+      if (useMemoMatch) {
+        callbackScopeName = useMemoMatch[1];
+      }
+    }
+
+    if (!callbackScopeName) return;
+
+    const callbackScope = this.scopeNodes[callbackScopeName];
+    if (!callbackScope) return;
+
+    // Look for returnValue.* sub-properties in the callback scope
+    if (!callbackScope.analysis?.isolatedEquivalentVariables) return;
+
+    const isolatedVars = callbackScope.analysis.isolatedEquivalentVariables;
+
+    // First, check if returnValue is an alias to another variable (e.g., returnValue = intermediate)
+    // If so, we need to look for that variable's sub-properties too
+    const returnValueAlias =
+      typeof isolatedVars.returnValue === 'string' &&
+      !isolatedVars.returnValue.includes('.')
+        ? isolatedVars.returnValue
+        : undefined;
+
+    // Pattern 3: Object.keys(X).reduce() - the reduce result has the same sub-properties as X
+    // When returnValue = "Object.keys(source).reduce(...).functionCallReturnValue", look for source.* sub-properties
+    let reduceSourceVar: string | undefined;
+    if (typeof isolatedVars.returnValue === 'string') {
+      const reduceMatch = isolatedVars.returnValue.match(
+        /^Object\.keys\((\w+)\)\.reduce\(.*\)\.functionCallReturnValue$/,
+      );
+      if (reduceMatch) {
+        reduceSourceVar = reduceMatch[1];
+      }
+    }
+
+    for (const [subPath, subValue] of Object.entries(isolatedVars)) {
+      // Check for direct returnValue.* sub-properties
+      const isReturnValueSub =
+        subPath.startsWith('returnValue.') ||
+        subPath.startsWith('returnValue[');
+
+      // Also check for alias.* sub-properties (e.g., intermediate.args when returnValue = intermediate)
+      const isAliasSub =
+        returnValueAlias &&
+        (subPath.startsWith(returnValueAlias + '.') ||
+          subPath.startsWith(returnValueAlias + '['));
+
+      // Also check for reduce source.* sub-properties (e.g., source['Function Arguments'] when returnValue = Object.keys(source).reduce())
+      const isReduceSourceSub =
+        reduceSourceVar &&
+        (subPath.startsWith(reduceSourceVar + '.') ||
+          subPath.startsWith(reduceSourceVar + '['));
+
+      if (
+        typeof subValue !== 'string' ||
+        (!isReturnValueSub && !isAliasSub && !isReduceSourceSub)
+      )
+        continue;
+
+      // Convert alias/reduceSource paths to returnValue paths
+      let effectiveSubPath = subPath;
+      if (isAliasSub && !isReturnValueSub) {
+        // Replace the alias prefix with returnValue
+        effectiveSubPath =
+          'returnValue' + subPath.substring(returnValueAlias!.length);
+      } else if (isReduceSourceSub && !isReturnValueSub && !isAliasSub) {
+        // Replace the reduce source prefix with returnValue
+        effectiveSubPath =
+          'returnValue' + subPath.substring(reduceSourceVar!.length);
+      }
+      const subPropertyPath = effectiveSubPath.substring('returnValue'.length);
+      const newPath = cleanPath(path + subPropertyPath, allPaths);
+      let newEquivalentValue = cleanPath(
+        subValue.replace(/::cyDuplicateKey\d+::/g, ''),
+        allPaths,
+      );
+
+      // Resolve variable references through parent scope equivalencies
+      const resolved = this.resolveVariableThroughParentScopes(
+        newEquivalentValue,
+        callbackScope,
+        allPaths,
+      );
+      newEquivalentValue = resolved.resolvedPath;
+      const equivalentScopeName = resolved.scopeName;
+
+      if (!newEquivalentValue || !this.isValidPath(newEquivalentValue))
+        continue;
+
+      this.addEquivalency(
+        newPath,
+        newEquivalentValue,
+        equivalentScopeName,
+        scopeNode,
+        'propagated function call return sub-property equivalency',
+      );
+
+      // Ensure the database entry has the usage path
+      this.addUsageToEquivalencyDatabaseEntry(
+        newPath,
+        newEquivalentValue,
+        equivalentScopeName,
+        scopeNode.name,
+      );
+    }
+  }
+
+  /**
+   * Resolves a variable path through parent scope equivalencies.
+   *
+   * For example, if the path is "dataStructure.arguments" and the parent scope has
+   * dataStructure -> signature[0].dataStructure, this returns:
+   *   { resolvedPath: "signature[0].dataStructure.arguments", scopeName: "ParentScope" }
+   */
+  private resolveVariableThroughParentScopes(
+    path: string | undefined,
+    callbackScope: ScopeNode,
+    allPaths: string[],
+  ): { resolvedPath: string | undefined; scopeName: string } {
+    if (!path)
+      return { resolvedPath: undefined, scopeName: callbackScope.name };
+
+    // Extract the root variable name
+    const dotIndex = path.indexOf('.');
+    const bracketIndex = path.indexOf('[');
+    let firstDelimiter = -1;
+    if (dotIndex > -1 && bracketIndex > -1) {
+      firstDelimiter = Math.min(dotIndex, bracketIndex);
+    } else {
+      firstDelimiter = dotIndex > -1 ? dotIndex : bracketIndex;
+    }
+
+    if (firstDelimiter === -1)
+      return { resolvedPath: path, scopeName: callbackScope.name };
+
+    const rootVar = path.substring(0, firstDelimiter);
+    const restOfPath = path.substring(firstDelimiter);
+
+    // Look in parent scopes for the root variable's equivalency
+    for (const parentScopeName of callbackScope.tree || []) {
+      const parentScope = this.scopeNodes[parentScopeName];
+      if (!parentScope?.analysis?.isolatedEquivalentVariables) continue;
+
+      const rootEquiv =
+        parentScope.analysis.isolatedEquivalentVariables[rootVar];
+      if (typeof rootEquiv === 'string') {
+        return {
+          resolvedPath: cleanPath(rootEquiv + restOfPath, allPaths),
+          scopeName: parentScopeName,
+        };
+      }
+    }
+
+    return { resolvedPath: path, scopeName: callbackScope.name };
+  }
+
+  /**
+   * Adds a usage path to the equivalency database entry that has the given source.
+   *
+   * The addEquivalency call creates the equivalency but doesn't always properly
+   * link the usage in the database, so we need to do it explicitly.
+   */
+  private addUsageToEquivalencyDatabaseEntry(
+    usagePath: string,
+    sourcePath: string,
+    sourceScopeName: string,
+    fallbackScopeName: string,
+  ) {
+    const usageEntry = {
+      scopeNodeName: usagePath.match(/^([^().]+)\(\)/)
+        ? (usagePath.match(/^([^().]+)\(\)/)?.[1] ?? fallbackScopeName)
+        : fallbackScopeName,
+      schemaPath: usagePath,
+    };
+
+    const sourceKey = `${sourceScopeName}::${sourcePath}`;
+    for (const entry of this.equivalencyDatabase) {
+      if (
+        entry.intermediatesOrder[sourceKey] === 0 ||
+        entry.sourceCandidates.some(
+          (sc) =>
+            sc.scopeNodeName === sourceScopeName &&
+            sc.schemaPath === sourcePath,
+        )
+      ) {
+        const usageExists = entry.usages.some(
+          (u) =>
+            u.scopeNodeName === usageEntry.scopeNodeName &&
+            u.schemaPath === usageEntry.schemaPath,
+        );
+        if (!usageExists) {
+          entry.usages.push(usageEntry);
+        }
+        break;
+      }
+    }
+  }
+
   private checkForArrayItemPath(
-    pathParts: string[],
+    pathParts: readonly string[],
     scopeNode: ScopeNode,
     equivalencyValueChain: EquivalencyValueChainItem[],
   ) {
-    const arrayItemPath = joinParenthesesAndArrays([...pathParts, '[]']);
+    const arrayItemPath = this.joinPathParts([...pathParts, '[]']);
     if (scopeNode.equivalencies[arrayItemPath]) {
       const firstEquivalency = equivalencyValueChain[0].currentPath;
-      const newFirstEquivalencyPath = joinParenthesesAndArrays([
-        ...splitOutsideParenthesesAndArrays(firstEquivalency.schemaPath),
+      const newFirstEquivalencyPath = this.joinPathParts([
+        ...this.splitPath(firstEquivalency.schemaPath),
         '[]',
       ]);
       this.addToSchema({
@@ -1383,41 +2282,95 @@ export class ScopeDataStructure {
     }
   }
 
+  /**
+   * Follows equivalencies for a subpath and recursively calls addToSchema.
+   *
+   * This is the recursive heart of schema propagation. When we have:
+   *   `user` equivalent to `props.user`
+   * And we're processing `user.id`, this method will:
+   * 1. Find the equivalency `user` → `props.user`
+   * 2. Reconstruct the full path: `props.user.id`
+   * 3. Recursively call addToSchema for the equivalent scope
+   *
+   * ## Function-Ambivalent Paths
+   *
+   * Handles paths like `data.map(fn)` by also checking equivalencies
+   * for `data.map` (without the function argument). This allows
+   * array method chains to propagate correctly.
+   *
+   * @param scopeNode - Current scope being processed
+   * @param path - Full original path (e.g., 'user.profile.name')
+   * @param pathParts - Split version of path
+   * @param subPath - Current subpath being checked (e.g., 'user.profile')
+   * @param subPathParts - Split version of subPath
+   * @param value - Type value to propagate
+   * @param equivalencyValueChain - Chain tracking for database
+   * @param traceId - Debug ID
+   * @param debugLevel - 0=minimal, 1=executed, 2=verbose
+   */
   private followEquivalencies(
     scopeNode: ScopeNode,
     path: string,
-    pathParts: string[],
+    pathParts: readonly string[],
     subPath: string,
-    subPathParts: string[],
+    subPathParts: readonly string[],
     value: string,
     equivalencyValueChain: EquivalencyValueChainItem[],
     traceId?: number,
     debugLevel = 0,
   ) {
     followEquivalenciesCallCount++;
+
+    // Trace for debugging
+    this.tracer.trace('followEquivalencies', {
+      path,
+      scope: scopeNode.name,
+      subPath,
+      hasEquivalencies: (scopeNode.equivalencies[subPath]?.length ?? 0) > 0,
+    });
+
     let propagated = false;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Step 1: Collect equivalencies (including function-ambivalent paths)
+    // ─────────────────────────────────────────────────────────────────────────
     let equivalentValues = scopeNode.equivalencies[subPath] ?? [];
     let functionAmbivalentSubPath = subPath;
     let functionAmbivalentSubPathParts = subPathParts;
 
-    if (subPathParts[subPathParts.length - 1].indexOf('(') > -1) {
+    // For paths like `data.map(fn)`, also check `data.map` equivalencies
+    // PERF: Only do the expensive function-ambivalent processing if:
+    // 1. No equivalencies found yet, AND
+    // 2. The subpath ends with a function call (contains '(')
+    const lastPart = subPathParts[subPathParts.length - 1];
+    if (lastPart.indexOf('(') > -1) {
+      // Check function-ambivalent path for equivalencies
       functionAmbivalentSubPathParts = [
         ...subPathParts.slice(0, -1),
-        subPathParts[subPathParts.length - 1].split('(')[0],
+        lastPart.split('(')[0],
       ];
       functionAmbivalentSubPath = this.joinPathParts(
         functionAmbivalentSubPathParts,
       );
-      equivalentValues = [
-        ...(equivalentValues ?? []),
-        ...(scopeNode.equivalencies[functionAmbivalentSubPath] ?? []),
-      ];
+      const functionAmbivalentEquivalencies =
+        scopeNode.equivalencies[functionAmbivalentSubPath];
+      if (functionAmbivalentEquivalencies?.length > 0) {
+        equivalentValues = [
+          ...equivalentValues,
+          ...functionAmbivalentEquivalencies,
+        ];
+      }
     }
 
     // Early exit optimization: if no equivalencies to follow, skip expensive processing
     if (equivalentValues.length === 0) {
+      followEquivalenciesEarlyExitCount++;
+      if (this.onlyEquivalencies) {
+        followEquivalenciesEarlyExitPhase1Count++;
+      }
       return false;
     }
+    followEquivalenciesWithWorkCount++;
 
     if (traceId && debugLevel > 1) {
       console.info(
@@ -1443,12 +2396,21 @@ export class ScopeDataStructure {
 
     const uniqueEquivalentValues = this.uniqueScopeVariables(equivalentValues);
 
+    // PERF: Only create Set when chain is non-empty (common case avoids allocation)
+    // Pre-compute Set of chain IDs for O(1) cycle detection instead of O(n) .some()
+    const chainIdSet =
+      equivalencyValueChain.length > 0
+        ? new Set(equivalencyValueChain.map((ev) => ev.id))
+        : null;
+
     for (let index = 0; index < uniqueEquivalentValues.length; ++index) {
       const equivalentValue = uniqueEquivalentValues[index];
 
+      // O(1) cycle check using Set instead of O(n) .some()
       if (
+        chainIdSet &&
         equivalentValue.id !== -1 &&
-        equivalencyValueChain.some((ev) => ev.id === equivalentValue.id)
+        chainIdSet.has(equivalentValue.id)
       ) {
         if (traceId) {
           console.info(
@@ -1499,8 +2461,12 @@ export class ScopeDataStructure {
         schemaPathParts[schemaPathParts.length - 1] ===
           lastRelevantSubPathPart.split('(')[0]
       ) {
-        schemaPathParts[schemaPathParts.length - 1] = lastRelevantSubPathPart;
-        schemaPath = this.joinPathParts(schemaPathParts);
+        // PERF: Don't mutate the array - create a new one to avoid requiring structuredClone
+        const updatedSchemaPathParts = [
+          ...schemaPathParts.slice(0, -1),
+          lastRelevantSubPathPart,
+        ];
+        schemaPath = this.joinPathParts(updatedSchemaPathParts);
       }
 
       const remainingPathParts = pathParts.slice(relevantSubPathParts.length);
@@ -1515,11 +2481,26 @@ export class ScopeDataStructure {
 
       const newEquivalentPath = this.joinPathParts([schemaPath, remainingPath]);
 
-      if (!equivalentScopeNode) {
-        if (traceId) {
-          console.info('Debug Propagation: missing equivalent scope info', {
-            traceId,
-            path,
+      // PERF: Detect repeated patterns in paths to prevent exponential blowup
+      // Paths like `signature[0].attributes.properties[].attributes.properties[]...`
+      // indicate recursive type structures that cause exponential schema explosion
+      if (this.hasExcessivePatternRepetition(newEquivalentPath)) {
+        if (traceId && debugLevel > 0) {
+          console.info(
+            'Debug: skipping path with excessive pattern repetition',
+            {
+              path: newEquivalentPath,
+            },
+          );
+        }
+        continue;
+      }
+
+      if (!equivalentScopeNode) {
+        if (traceId) {
+          console.info('Debug Propagation: missing equivalent scope info', {
+            traceId,
+            path,
             subPath,
             functionAmbivalentSubPath,
             scopeNodeName: scopeNode.name,
@@ -1560,25 +2541,27 @@ export class ScopeDataStructure {
           );
         }
 
-        const localEquivalencyValueChain = structuredClone(
-          equivalencyValueChain,
-        );
-        localEquivalencyValueChain.push({
-          id: equivalentValue.id,
-          source: 'equivalence',
-          previousPath: {
-            scopeNodeName: scopeNode.name,
-            schemaPath: path,
-            value,
-          },
-          currentPath: {
-            scopeNodeName: equivalentScopeNode.name,
-            schemaPath: newEquivalentPath,
-            value,
+        // PERF: Use spread instead of structuredClone - the chain items are immutable
+        // so shallow copy is sufficient and much faster (structuredClone is expensive)
+        const localEquivalencyValueChain = [
+          ...equivalencyValueChain,
+          {
+            id: equivalentValue.id,
+            source: 'equivalence',
+            previousPath: {
+              scopeNodeName: scopeNode.name,
+              schemaPath: path,
+              value,
+            },
+            currentPath: {
+              scopeNodeName: equivalentScopeNode.name,
+              schemaPath: newEquivalentPath,
+              value,
+            },
+            reason: equivalentValue.equivalencyReason,
+            traceId,
           },
-          reason: equivalentValue.equivalencyReason,
-          traceId,
-        });
+        ];
 
         // writeEquivalencyToFile(
         //   scopeNode.name,
@@ -1590,13 +2573,57 @@ export class ScopeDataStructure {
         // )
 
         propagated = true;
-        this.addToSchema({
-          path: newEquivalentPath,
-          value,
-          scopeNode: equivalentScopeNode,
-          equivalencyValueChain: localEquivalencyValueChain,
-          traceId,
-        });
+
+        // PERF: If batch processor is active, queue work instead of recursing
+        // This converts deep recursion to iterative processing
+        if (this.batchProcessor) {
+          // PERF OPTIMIZATION: For external function calls, use path-only key (ignore value)
+          // External FCs don't have internals to analyze, so processing the same path
+          // with different values is redundant - we're just tracking data flow
+          const isExternalFc =
+            equivalentValue.equivalencyReason ===
+              'equivalency to external function call' ||
+            this.getExternalFunctionCallInfo(equivalentScopeNode.name) !==
+              undefined;
+          const queueKey = isExternalFc
+            ? `${equivalentScopeNode.name}::${newEquivalentPath}` // path-only for external FC
+            : `${equivalentScopeNode.name}::${newEquivalentPath}::${value}`; // full key otherwise
+
+          // Always check visited - it catches already-processed items
+          const alreadyVisited = this.visitedTracker.hasGlobalVisited(
+            equivalentScopeNode.name,
+            newEquivalentPath,
+            value,
+          );
+          // For external FCs, queueKey is path-only so this catches any-value duplicates
+          const alreadyQueued = this.batchQueuedSet?.has(queueKey);
+
+          if (alreadyVisited || alreadyQueued) {
+            // Still record in database to capture the chain (as addToSchema does)
+            this.addToEquivalencyDatabase(
+              localEquivalencyValueChain as EquivalencyValueChainItem[],
+              traceId,
+            );
+          } else {
+            // Mark as queued to prevent duplicate queue entries
+            this.batchQueuedSet?.add(queueKey);
+            this.batchProcessor.addWork({
+              scopeNodeName: equivalentScopeNode.name,
+              path: newEquivalentPath,
+              value,
+              equivalencyValueChain: localEquivalencyValueChain,
+              traceId,
+            });
+          }
+        } else {
+          this.addToSchema({
+            path: newEquivalentPath,
+            value,
+            scopeNode: equivalentScopeNode,
+            equivalencyValueChain: localEquivalencyValueChain,
+            traceId,
+          });
+        }
       }
     }
 
@@ -1635,6 +2662,17 @@ export class ScopeDataStructure {
             usageEquivalency.scopeNodeName,
           ) as ScopeNode;
 
+          // Guard against infinite recursion by tracking which paths we've already
+          // added from addComplexSourcePathVariables
+          if (
+            this.visitedTracker.checkAndMarkComplexSourceVisited(
+              usageScopeNode.name,
+              newUsageEquivalentPath,
+            )
+          ) {
+            continue;
+          }
+
           this.addToSchema({
             path: newUsageEquivalentPath,
             value: 'unknown',
@@ -1785,6 +2823,7 @@ export class ScopeDataStructure {
 
     for (let i = 0; i < cleanEquivalencyValueChain.length; ++i) {
       const pathInfo = cleanEquivalencyValueChain[i].currentPath;
+      const previousPath = cleanEquivalencyValueChain[i].previousPath;
 
       const schemaPathParts = this.splitPath(pathInfo.schemaPath);
       const isSignaturePath =
@@ -1798,6 +2837,21 @@ export class ScopeDataStructure {
         databaseEntry.usages.push(pathInfo);
       }
 
+      // Also add previousPath as a usage if it matches the criteria
+      // This handles propagated sub-property equivalencies where the JSX prop path
+      // is in previousPath and should be tracked as a usage
+      if (previousPath) {
+        const prevSchemaPathParts = this.splitPath(previousPath.schemaPath);
+        const isPrevSignaturePath =
+          prevSchemaPathParts.findIndex((p) => p.startsWith('signature[')) > 0;
+        if (
+          prevSchemaPathParts[0].startsWith('returnValue') ||
+          isPrevSignaturePath
+        ) {
+          databaseEntry.usages.push(previousPath);
+        }
+      }
+
       const pathId = this.uniqueId(pathInfo);
       let intermediateIndex = cleanEquivalencyValueChain.length - i - 1;
       const existingIntermediateIndex =
@@ -1905,6 +2959,7 @@ export class ScopeDataStructure {
       if (functionScope) {
         functionScope.functionCalls.push(externalFunctionCallInfo);
         this.externalFunctionCalls.splice(i, 1);
+        this.invalidateExternalFunctionCallsIndex();
 
         for (const equivalentPath in externalFunctionCallInfo.equivalencies) {
           let localEquivalentPath = equivalentPath;
@@ -1972,18 +3027,21 @@ export class ScopeDataStructure {
     for (const key in scopeNode.equivalencies) {
       const keyParts = this.splitPath(key);
       if (keyParts.length > 1) {
-        const lastPart = keyParts.pop();
+        // PERF: Don't mutate the array - use indexing instead of pop() to avoid requiring structuredClone
+        const lastPart = keyParts[keyParts.length - 1];
         if (lastPart.startsWith('signature[')) {
-          const functionCall = keyParts[keyParts.length - 1];
+          const keyPartsWithoutLast = keyParts.slice(0, -1);
+          const functionCall =
+            keyPartsWithoutLast[keyPartsWithoutLast.length - 1];
           const argumentsIndex = functionCall.indexOf('(');
           const functionName = this.joinPathParts([
-            ...keyParts.slice(0, -1),
+            ...keyPartsWithoutLast.slice(0, -1),
             functionCall.slice(
               0,
               argumentsIndex === -1 ? undefined : argumentsIndex,
             ),
           ]);
-          const callSignature = this.joinPathParts(keyParts);
+          const callSignature = this.joinPathParts(keyPartsWithoutLast);
 
           const functionCallInfo = {
             name: functionName,
@@ -2000,19 +3058,21 @@ export class ScopeDataStructure {
           equivalentValues.schemaPath,
         );
         if (equivalentValueParts.length > 1) {
-          const lastPart = equivalentValueParts.pop();
+          // PERF: Don't mutate the array - use indexing instead of pop() to avoid requiring structuredClone
+          const lastPart =
+            equivalentValueParts[equivalentValueParts.length - 1];
           if (lastPart.startsWith('functionCallReturnValue')) {
-            const functionCall =
-              equivalentValueParts[equivalentValueParts.length - 1];
+            const partsWithoutLast = equivalentValueParts.slice(0, -1);
+            const functionCall = partsWithoutLast[partsWithoutLast.length - 1];
             const argumentsIndex = functionCall.indexOf('(');
             const functionName = this.joinPathParts([
-              ...equivalentValueParts.slice(0, -1),
+              ...partsWithoutLast.slice(0, -1),
               functionCall.slice(
                 0,
                 argumentsIndex === -1 ? undefined : argumentsIndex,
               ),
             ]);
-            const callSignature = this.joinPathParts(equivalentValueParts);
+            const callSignature = this.joinPathParts(partsWithoutLast);
 
             const functionCallInfo = {
               name: functionName,
@@ -2213,7 +3273,8 @@ export class ScopeDataStructure {
   }
 
   getScopeNode(scopeName?: string): ScopeNode | undefined {
-    const scopeNode = this.scopeNodes[scopeName ?? this.scopeTree.name];
+    const scopeNode =
+      this.scopeNodes[scopeName ?? this.scopeTreeManager.getRootName()];
     if (scopeNode) return scopeNode;
 
     for (const scopeNodeName in this.scopeNodes) {
@@ -2223,18 +3284,54 @@ export class ScopeDataStructure {
     }
   }
 
+  /**
+   * Gets or builds the external function calls index for O(1) lookup.
+   * The index maps both the full name and the name without generics to the FunctionCallInfo.
+   */
+  private getExternalFunctionCallsIndex(): Map<string, FunctionCallInfo> {
+    if (this.externalFunctionCallsIndex === null) {
+      this.externalFunctionCallsIndex = new Map();
+      for (const efc of this.externalFunctionCalls) {
+        this.externalFunctionCallsIndex.set(efc.name, efc);
+        // Also index by name without generics (e.g., 'MyFunction<T>' -> 'MyFunction')
+        const nameWithoutGenerics = this.pathManager.stripGenerics(efc.name);
+        if (nameWithoutGenerics !== efc.name) {
+          this.externalFunctionCallsIndex.set(nameWithoutGenerics, efc);
+        }
+      }
+    }
+    return this.externalFunctionCallsIndex;
+  }
+
+  /**
+   * Invalidates the external function calls index.
+   * Call this after any mutation to externalFunctionCalls array.
+   */
+  private invalidateExternalFunctionCallsIndex(): void {
+    this.externalFunctionCallsIndex = null;
+  }
+
   getExternalFunctionCallInfo(
     functionName: string,
   ): FunctionCallInfo | undefined {
+    const searchKey = getFunctionCallRoot(functionName);
+    const index = this.getExternalFunctionCallsIndex();
+
+    // First try exact match
+    const exact = index.get(searchKey);
+    if (exact) return exact;
+
+    // Fallback to the original find for edge cases not covered by index
     return this.externalFunctionCalls.find(
       (efc) =>
-        efc.name === getFunctionCallRoot(functionName) ||
-        efc.name.split('<')[0] === getFunctionCallRoot(functionName),
+        efc.name === searchKey ||
+        this.pathManager.stripGenerics(efc.name) === searchKey,
     );
   }
 
   getScopeAnalysis(scopeName?: string): ScopeAnalysis | undefined {
-    return this.scopeNodes[scopeName ?? this.scopeTree.name].analysis;
+    return this.scopeNodes[scopeName ?? this.scopeTreeManager.getRootName()]
+      .analysis;
   }
 
   getAnalysisTree(): ScopeTreeNode {
@@ -2248,12 +3345,13 @@ export class ScopeDataStructure {
     scopeName?: string;
     fillInUnknowns?: boolean;
   }): any {
-    const scopeNode = this.scopeNodes[scopeName ?? this.scopeTree.name];
+    const scopeNode =
+      this.scopeNodes[scopeName ?? this.scopeTreeManager.getRootName()];
 
     if (!scopeNode) {
-      const externalFunctionCallSchema = this.externalFunctionCalls.find(
-        (call) => call.name === getFunctionCallRoot(scopeName),
-      )?.schema;
+      const searchKey = getFunctionCallRoot(scopeName);
+      const externalFunctionCallSchema =
+        this.getExternalFunctionCallsIndex().get(searchKey)?.schema;
 
       if (!externalFunctionCallSchema) return;
 
@@ -2268,10 +3366,68 @@ export class ScopeDataStructure {
       );
     }
 
+    // CRITICAL: Set onlyEquivalencies to true to prevent database modifications
+    // during this "getter" method. See comment in getFunctionSignature.
+    const wasOnlyEquivalencies = this.onlyEquivalencies;
+    this.onlyEquivalencies = true;
     this.validateSchema(scopeNode, true, fillInUnknowns);
+    this.onlyEquivalencies = wasOnlyEquivalencies;
 
     const { schema } = scopeNode;
-    return schema;
+
+    // For root scope, merge in external function call schemas
+    // This ensures that imported objects used as method call targets (like logger.error())
+    // appear in the schema as objects with function properties
+    if (
+      scopeName === undefined ||
+      scopeName === this.scopeTreeManager.getRootName()
+    ) {
+      const mergedSchema = { ...schema };
+      for (const efc of this.externalFunctionCalls) {
+        // Add the base object name (e.g., "logger") as an object
+        const baseName = this.splitPath(efc.name)[0];
+        if (!mergedSchema[baseName]) {
+          mergedSchema[baseName] = 'object';
+        }
+
+        // Get all call signatures (use allCallSignatures if available, otherwise just the single callSignature)
+        const signatures = efc.allCallSignatures ?? [efc.callSignature];
+        for (const signature of signatures) {
+          // Add the method as a function (e.g., "logger.error")
+          // Extract method name from callSignature like "logger.error(args...)"
+          // Get everything before the first '(' to get "logger.error"
+          const parenIndex = signature.indexOf('(');
+          if (parenIndex > 0) {
+            const methodPath = signature.substring(0, parenIndex);
+            if (methodPath.includes('.') && !mergedSchema[methodPath]) {
+              mergedSchema[methodPath] = 'function';
+            }
+          }
+        }
+      }
+      return this.filterDuplicateKeys(mergedSchema);
+    }
+
+    return this.filterDuplicateKeys(schema);
+  }
+
+  /**
+   * Filter out ::cyDuplicateKey:: entries from a schema.
+   * These are internal markers for tracking variable reassignments
+   * and should not appear in output schemas or LLM prompts.
+   */
+  private filterDuplicateKeys(
+    schema: Record<string, string>,
+  ): Record<string, string> {
+    return Object.entries(schema).reduce(
+      (acc, [key, value]) => {
+        if (!key.includes('::cyDuplicateKey')) {
+          acc[key] = value;
+        }
+        return acc;
+      },
+      {} as Record<string, string>,
+    );
   }
 
   getEquivalencies(scopeName?: string) {
@@ -2286,9 +3442,9 @@ export class ScopeDataStructure {
       return this.equivalencyDatabaseCache.get(cacheKey);
     }
 
-    const result = this.equivalencyDatabase.find(
-      (entry) => entry.intermediatesOrder[cacheKey] !== undefined,
-    );
+    // PERF: Use inverted index for O(1) lookup instead of O(n) array scan
+    // The intermediatesOrderIndex maps pathId (scopeNodeName::schemaPath) to entry
+    const result = this.intermediatesOrderIndex.get(cacheKey);
 
     this.equivalencyDatabaseCache.set(cacheKey, result);
     return result;
@@ -2335,6 +3491,7 @@ export class ScopeDataStructure {
         (candidate) => candidate.scopeNodeName === scopeNode.name,
       ),
     );
+
     return entries.reduce(
       (acc, entry) => {
         if (entry.usages.length === 0) return acc;
@@ -2378,12 +3535,14 @@ export class ScopeDataStructure {
       );
 
     const equivalencies = this.getEquivalencies(functionName);
+    const scopeName = functionName ?? this.scopeTreeManager.getRootName();
+
     for (const equivalenceKey in equivalencies ?? {}) {
       for (const equivalenceValue of equivalencies[equivalenceKey]) {
         const schemaPath = equivalenceValue.schemaPath;
         if (
           schemaPath.startsWith('signature[') &&
-          equivalenceValue.scopeNodeName === functionName &&
+          equivalenceValue.scopeNodeName === scopeName &&
           !signatureInSchema[schemaPath]
         ) {
           signatureInSchema[schemaPath] = 'unknown';
@@ -2392,14 +3551,67 @@ export class ScopeDataStructure {
     }
 
     const tempScopeNode = this.createTempScopeNode(
-      functionName ?? this.scopeTree.name,
+      functionName ?? this.scopeTreeManager.getRootName(),
       signatureInSchema,
       equivalencies,
     );
 
     this.validateSchema(tempScopeNode, true, fillInUnknowns);
 
-    return tempScopeNode.schema;
+    // After validateSchema has filled in types, propagate nested paths from
+    // variables to their signature equivalents.
+    // e.g., workouts[].activity_type -> signature[0].workouts[].activity_type
+    //
+    // Build a map of variable names that are equivalent to signature paths
+    // e.g., { 'workouts': 'signature[0].workouts' }
+    const variableToSignatureMap: Record<string, string> = {};
+
+    for (const equivalenceKey in equivalencies ?? {}) {
+      for (const equivalenceValue of equivalencies[equivalenceKey]) {
+        const schemaPath = equivalenceValue.schemaPath;
+        // Track which variables map to signature paths
+        // equivalenceKey is the variable name (e.g., 'workouts')
+        // schemaPath is where it comes from (e.g., 'signature[0].workouts')
+        if (
+          schemaPath.startsWith('signature[') &&
+          equivalenceValue.scopeNodeName === scopeName
+        ) {
+          variableToSignatureMap[equivalenceKey] = schemaPath;
+        }
+      }
+    }
+
+    // Propagate nested paths from variables to their signature equivalents
+    // e.g., if workouts = signature[0].workouts, then workouts[].title becomes
+    // signature[0].workouts[].title
+    for (const schemaKey in schema) {
+      // Skip keys that already start with signature[
+      if (schemaKey.startsWith('signature[')) continue;
+
+      // Check if this key starts with a variable that maps to a signature path
+      for (const [variableName, signaturePath] of Object.entries(
+        variableToSignatureMap,
+      )) {
+        // Check if schemaKey starts with variableName followed by a property accessor
+        // e.g., 'workouts[]' starts with 'workouts'
+        if (
+          schemaKey === variableName ||
+          schemaKey.startsWith(variableName + '.') ||
+          schemaKey.startsWith(variableName + '[')
+        ) {
+          // Transform the path: replace the variable prefix with the signature path
+          const suffix = schemaKey.slice(variableName.length);
+          const signatureKey = signaturePath + suffix;
+
+          // Add to schema if not already present
+          if (!tempScopeNode.schema[signatureKey]) {
+            tempScopeNode.schema[signatureKey] = schema[schemaKey];
+          }
+        }
+      }
+    }
+
+    return this.filterDuplicateKeys(tempScopeNode.schema);
   }
 
   getReturnValue({
@@ -2409,7 +3621,16 @@ export class ScopeDataStructure {
     functionName?: string;
     fillInUnknowns?: boolean;
   }) {
-    const scopeName = functionName ?? this.scopeTree.name;
+    // Trigger finalization on all managers to apply any pending updates
+    // (e.g., ref type propagation to external function call schemas)
+    const rootScope = this.scopeNodes[this.scopeTreeManager.getRootName()];
+    if (rootScope) {
+      for (const manager of this.equivalencyManagers) {
+        manager.finalize(rootScope, this);
+      }
+    }
+
+    const scopeName = functionName ?? this.scopeTreeManager.getRootName();
     const scopeNode = this.scopeNodes[scopeName];
 
     let schema: ScopeNode['schema'] = {};
@@ -2419,7 +3640,8 @@ export class ScopeDataStructure {
         scopeNode: scopeNode,
       });
     } else {
-      for (const externalFunctionCall of this.externalFunctionCalls) {
+      // Use getExternalFunctionCalls() which cleans cyScope from schemas
+      for (const externalFunctionCall of this.getExternalFunctionCalls()) {
         const functionNameParts = this.splitPath(functionName).map((p) =>
           this.functionOrScopeName(p),
         );
@@ -2434,14 +3656,7 @@ export class ScopeDataStructure {
           for (const schemaPath in externalFunctionCall.schema) {
             const value1 = schema[schemaPath];
             const value2 = externalFunctionCall.schema[schemaPath];
-            let bestValue = value1 ?? value2;
-            if (
-              bestValue === 'unknown' ||
-              (bestValue.includes('unknown') && !value2.includes('unknown'))
-            ) {
-              bestValue = value2;
-            }
-            schema[schemaPath] = bestValue;
+            schema[schemaPath] = selectBestValue(value1, value2, value2);
           }
         }
       }
@@ -2458,7 +3673,17 @@ export class ScopeDataStructure {
           // Include function paths even if their return value wasn't captured
           // This ensures methods like onAuthStateChange are included in the schema
           // But exclude signature entries (they should only be included via functionCallReturnValue paths)
-          (schema[key] === 'function' && key.indexOf('signature[') === -1),
+          // Also exclude bare function call signatures - paths that are JUST a call like
+          // "useCustomSizes(projectSlug)" should not be included as return values.
+          // These represent "the function exists" not actual return data, and including
+          // them causes nested path bugs in dependencySchemas.
+          (schema[key] === 'function' &&
+            key.indexOf('signature[') === -1 &&
+            // Exclude bare call signatures: function calls with no dots OUTSIDE parentheses
+            // e.g., "useCustomSizes(projectSlug)" is bare (exclude)
+            // e.g., "loadProject({nested.property})" is bare - dots are inside args (exclude)
+            // e.g., "getSupabase().auth.method()" has dots outside - method chain (include)
+            !this.isBareCallSignature(key)),
       )
       .reduce(
         (acc, key) => {
@@ -2468,7 +3693,10 @@ export class ScopeDataStructure {
           for (const path in schema) {
             const pathParts = this.splitPath(path);
             if (pathParts.every((p, i) => keyParts[i] === p)) {
-              acc[path] = schema[path];
+              // Also exclude bare call signatures from prefix paths
+              if (!this.isBareCallSignature(path)) {
+                acc[path] = schema[path];
+              }
             }
           }
 
@@ -2482,14 +3710,73 @@ export class ScopeDataStructure {
 
     const tempScopeNode = this.createTempScopeNode(scopeName, resolvedSchema);
 
+    // CRITICAL: Set onlyEquivalencies to true to prevent database modifications
+    // during this "getter" method. See comment in getFunctionSignature.
+    const wasOnlyEquivalencies = this.onlyEquivalencies;
+    this.onlyEquivalencies = true;
     this.validateSchema(tempScopeNode, true, fillInUnknowns);
+    this.onlyEquivalencies = wasOnlyEquivalencies;
+
+    // Remove bare call signatures from the return value schema.
+    // fillInSchemaGapsAndUnknowns may add parent paths like "useCustomSizes(projectSlug)"
+    // when it sees "useCustomSizes(projectSlug).functionCallReturnValue". These bare
+    // call signatures represent "the function exists" not actual return data, and
+    // including them causes nested path bugs in dependencySchemas.
+    const resultSchema = tempScopeNode.schema;
+    for (const key of Object.keys(resultSchema)) {
+      if (this.isBareCallSignature(key)) {
+        delete resultSchema[key];
+      }
+    }
+
+    return resultSchema;
+  }
+
+  /**
+   * Checks if a schema key is a "bare call signature" - a function call with no
+   * method chain before it and no path segments after it.
+   *
+   * A bare call signature represents "this function exists" rather than actual
+   * return data, and including them causes nested path bugs in dependencySchemas.
+   *
+   * Examples:
+   * - "useCustomSizes(projectSlug)" -> bare (true)
+   * - "loadProject({nested.property})" -> bare (dots are inside args, true)
+   * - "getSupabase().auth.method()" -> not bare (has dots outside parens, false)
+   * - "useProject().functionCallReturnValue" -> not bare (has path after, false)
+   */
+  private isBareCallSignature(key: string): boolean {
+    // Must end with ) and contain ( to be a call
+    if (!key.endsWith(')') || key.indexOf('(') === -1) {
+      return false;
+    }
+
+    // Check if there are any dots OUTSIDE of parentheses
+    // Strip out content inside balanced parentheses, then check for dots
+    let depth = 0;
+    let hasDotsOutsideParens = false;
+
+    for (let i = 0; i < key.length; i++) {
+      const char = key[i];
+      if (char === '(') {
+        depth++;
+      } else if (char === ')') {
+        depth--;
+      } else if (char === '.' && depth === 0) {
+        hasDotsOutsideParens = true;
+        break;
+      }
+    }
 
-    return tempScopeNode.schema;
+    // It's a bare call signature if there are no dots outside parentheses
+    return !hasDotsOutsideParens;
   }
 
   /**
    * Replaces cyScope placeholder references (e.g., cyScope10()) in schema keys
    * with the actual callback function text from the corresponding scope node.
+   * If the scope text can't be found, uses a generic fallback to avoid leaking
+   * internal cyScope names into stored data.
    */
   private replaceCyScopePlaceholders(
     schema: Record<string, string>,
@@ -2505,10 +3792,10 @@ export class ScopeDataStructure {
       for (const match of matches) {
         const cyScopeName = `cyScope${match[1]}`;
         const scopeText = this.findCyScopeText(cyScopeName);
-        if (scopeText) {
-          // Replace cyScope10() with the actual callback text
-          newKey = newKey.replace(match[0], scopeText);
-        }
+        // Always replace cyScope references - use actual text if available,
+        // otherwise use a generic callback placeholder
+        const replacement = scopeText || '() => {}';
+        newKey = newKey.replace(match[0], replacement);
       }
 
       result[newKey] = value;
@@ -2567,17 +3854,269 @@ export class ScopeDataStructure {
   }
 
   getEquivalentSignatureVariables() {
-    const scopeNode = this.scopeNodes[this.scopeTree.name];
+    const scopeNode = this.scopeNodes[this.scopeTreeManager.getRootName()];
 
     const equivalentSignatureVariables: Record<string, string> = {};
     for (const [path, equivalentValues] of Object.entries(
       scopeNode.equivalencies,
     )) {
       for (const equivalentValue of equivalentValues) {
+        // Case 1: Props/signature equivalencies (existing behavior)
+        // Maps local variable names to their signature paths
+        // e.g., "propValue" -> "signature[0].prop"
         if (path.startsWith('signature[')) {
           equivalentSignatureVariables[equivalentValue.schemaPath] = path;
         }
+
+        // Case 2: Hook variable equivalencies (new behavior)
+        // The equivalencies are stored as: path = variable name, schemaPath = data source
+        // e.g., path = "debugFetcher", schemaPath = "useFetcher<...>().functionCallReturnValue"
+        // We need to map: "debugFetcher" -> "useFetcher<...>()"
+        // This enables resolving paths like "debugFetcher.state" to
+        // "useFetcher<...>().state" for execution flow validation
+        if (equivalentValue.schemaPath.endsWith('.functionCallReturnValue')) {
+          // Extract the hook call path (everything before .functionCallReturnValue)
+          const hookCallPath = equivalentValue.schemaPath.slice(
+            0,
+            -'.functionCallReturnValue'.length,
+          );
+          // Only include if it looks like a hook call (contains parentheses)
+          // and the variable name (path) is a simple identifier (no dots)
+          if (hookCallPath.includes('(') && !path.includes('.')) {
+            equivalentSignatureVariables[path] = hookCallPath;
+          }
+        }
+
+        // Case 3: Destructured variables from local variables
+        // e.g., const { scenarios } = currentEntityAnalysis;
+        // This creates: path = "scenarios", schemaPath = "currentEntityAnalysis.scenarios"
+        // We need to map: "scenarios" -> "currentEntityAnalysis.scenarios"
+        // AND resolve transitively if currentEntityAnalysis is itself equivalent to a hook call
+        if (
+          !path.includes('.') && // path is a simple identifier
+          !equivalentValue.schemaPath.startsWith('signature[') && // not a signature path
+          !equivalentValue.schemaPath.endsWith('.functionCallReturnValue') // not already handled above
+        ) {
+          // Only add if we haven't already captured this variable in Case 1 or 2
+          if (!(path in equivalentSignatureVariables)) {
+            equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+          }
+        }
+
+        // Case 4: Child component prop mappings (Fix 22)
+        // When parent renders <ChildComponent prop={value} />, we get equivalencies like:
+        //   path = "ChildComponent().signature[0].prop"
+        //   schemaPath = "value" (the variable passed as the prop)
+        // We need to include these so translateChildPathToParent can work.
+        // Pattern: ComponentName().signature[N] or ComponentName().signature[N].propName
+        if (
+          path.includes('().signature[') &&
+          !equivalentValue.schemaPath.includes('()') // schemaPath is a simple variable, not a function call
+        ) {
+          equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+        }
+
+        // Case 5: Destructured function parameters (Fix 25)
+        // When a function has destructured props: function Comp({ propA, propB }: Props)
+        // We get equivalencies like:
+        //   path = "propA" (the destructured variable name)
+        //   schemaPath = "signature[0].propA" (the signature path)
+        // We need to map: "propA" -> "signature[0].propA"
+        // This enables translateChildPathToParent to resolve child variable paths
+        // to their signature paths when merging execution flows.
+        if (
+          !path.includes('.') && // path is a simple identifier (destructured prop name)
+          equivalentValue.schemaPath.startsWith('signature[') // schemaPath IS a signature path
+        ) {
+          equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+        }
+
+        // Case 7: Method calls on variables that result in .functionCallReturnValue (Fix 33)
+        // When we have patterns like:
+        //   path = "segments" (simple identifier)
+        //   schemaPath = "splat.split('/').functionCallReturnValue"
+        // This is a method call on a variable (not a hook call), but we still need to
+        // track it so transitive resolution can resolve `splat` to its actual source.
+        // E.g., if splat -> useParams().functionCallReturnValue['*'], then
+        // segments -> useParams().functionCallReturnValue['*'].split('/').functionCallReturnValue
+        if (
+          !path.includes('.') && // path is a simple identifier
+          equivalentValue.schemaPath.endsWith('.functionCallReturnValue') && // ends with function return
+          equivalentValue.schemaPath.includes('.') && // has property access (method call)
+          !(path in equivalentSignatureVariables) // not already captured
+        ) {
+          // Check if this looks like a method call on a variable (not a hook call)
+          // Hook calls look like: hookName() or hookName<T>()
+          // Method calls look like: variable.method() or variable.method<T>()
+          const hookCallPath = equivalentValue.schemaPath.slice(
+            0,
+            -'.functionCallReturnValue'.length,
+          );
+          // If it's a method call (contains a dot before the parenthesis), include it
+          const dotBeforeParen = hookCallPath.indexOf('.');
+          const parenPos = hookCallPath.indexOf('(');
+          if (dotBeforeParen !== -1 && dotBeforeParen < parenPos) {
+            // This is a method call like "splat.split('/')", not a hook call
+            equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+          }
+        }
+      }
+    }
+
+    // Case 6: Collect JSX child prop equivalencies from child scopes (Fix 26)
+    // When a parent component renders <ChildComponent prop={value} />, the JSX
+    // return statement may be in a child scope (e.g., cyScope2). The equivalencies
+    // like ChildComponent().signature[0].prop -> value get stored in that child scope.
+    // But translateChildPathToParent needs to find them from the parent scope's context.
+    // So we collect Case 4 patterns from ALL child scopes that belong to this root scope.
+    const rootName = this.scopeTreeManager.getRootName();
+    for (const [scopeName, childScopeNode] of Object.entries(this.scopeNodes)) {
+      // Skip the root scope (already processed above)
+      if (scopeName === rootName) continue;
+
+      // Only include scopes that are children of the root (their tree includes root)
+      if (!childScopeNode.tree?.includes(rootName)) continue;
+
+      // Look for Case 4 patterns in the child scope
+      for (const [path, equivalentValues] of Object.entries(
+        childScopeNode.equivalencies || {},
+      )) {
+        for (const equivalentValue of equivalentValues) {
+          // Case 4 pattern: ChildComponent().signature[0].propName -> parentVariable
+          if (
+            path.includes('().signature[') &&
+            !equivalentValue.schemaPath.includes('()') // schemaPath is a simple variable
+          ) {
+            // Only add if not already present from the root scope
+            if (!(path in equivalentSignatureVariables)) {
+              equivalentSignatureVariables[path] = equivalentValue.schemaPath;
+            }
+          }
+        }
+      }
+    }
+
+    // Transitive resolution: Resolve variable chains through multiple levels
+    // E.g., analysis → currentEntityAnalysis → useLoaderData().functionCallReturnValue.currentEntityAnalysis
+    // We need multiple passes because resolutions can depend on each other
+    const maxIterations = 5; // Prevent infinite loops
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+      let changed = false;
+
+      for (const [varName, sourcePath] of Object.entries(
+        equivalentSignatureVariables,
+      )) {
+        // Skip if already fully resolved (contains function call syntax)
+        // BUT first check for computed value patterns that need resolution (Fix 28)
+        // AND method call patterns that need base variable resolution (Fix 33)
+        if (sourcePath.includes('()')) {
+          // Fix 28: Handle computed value patterns with dependency arrays
+          // Patterns like `functionName(arg, [dep1, dep2, ...])` are NOT controllable
+          // data sources. We trace through the dependencies to find controllable sources.
+          const bracketStart = sourcePath.indexOf('[');
+          const bracketEnd = sourcePath.lastIndexOf(']');
+
+          if (bracketStart !== -1 && bracketEnd > bracketStart) {
+            const arrayContent = sourcePath.slice(bracketStart + 1, bracketEnd);
+            const items = arrayContent.split(',').map((s) => s.trim());
+
+            // Only process if this looks like a dependency array:
+            // multiple items that are all simple identifiers (not numbers or expressions)
+            const isIdentifier = (s: string) =>
+              /^\w+$/.test(s) && !/^\d+$/.test(s);
+            if (items.length > 1 && items.every(isIdentifier)) {
+              // Look for a dependency that's already resolved to a controllable source
+              for (const dep of items) {
+                if (dep in equivalentSignatureVariables) {
+                  const resolvedDep = equivalentSignatureVariables[dep];
+                  // Use if it's a controllable path (contains hook call)
+                  // and is NOT another unresolved computed pattern (has comma-separated deps)
+                  const hasCommaInBrackets =
+                    resolvedDep.includes('[') &&
+                    resolvedDep.includes(',') &&
+                    resolvedDep.indexOf(',') > resolvedDep.indexOf('[');
+                  if (resolvedDep.includes('()') && !hasCommaInBrackets) {
+                    // Computed value is typically an element from an array
+                    equivalentSignatureVariables[varName] = resolvedDep + '[]';
+                    changed = true;
+                    break;
+                  }
+                }
+              }
+            }
+          }
+
+          // Fix 33: Handle method call patterns on variables
+          // Patterns like: "splat.split('/').functionCallReturnValue"
+          // We need to resolve the base variable (splat) to its actual source
+          // Check if this is a method call on a variable (dot before first parenthesis)
+          const dotIndex = sourcePath.indexOf('.');
+          const parenIndex = sourcePath.indexOf('(');
+          if (
+            dotIndex !== -1 &&
+            dotIndex < parenIndex &&
+            !sourcePath.startsWith('use') // Not a hook call like useState()
+          ) {
+            // Extract the base variable (before the first dot)
+            const baseVar = sourcePath.slice(0, dotIndex);
+            const rest = sourcePath.slice(dotIndex); // includes ".method(...).functionCallReturnValue"
+
+            // Check if the base variable can be resolved
+            if (
+              baseVar in equivalentSignatureVariables &&
+              baseVar !== varName
+            ) {
+              const baseResolved = equivalentSignatureVariables[baseVar];
+              // Only resolve if the base resolved to something useful (contains () or .)
+              if (baseResolved.includes('()') || baseResolved.includes('.')) {
+                const newPath = baseResolved + rest;
+                if (newPath !== equivalentSignatureVariables[varName]) {
+                  equivalentSignatureVariables[varName] = newPath;
+                  changed = true;
+                }
+              }
+            }
+          }
+
+          continue;
+        }
+
+        // Check if the source path starts with a variable that's also in the map
+        const dotIndex = sourcePath.indexOf('.');
+        let baseVar: string;
+        let rest: string;
+
+        if (dotIndex > 0) {
+          // Path has a dot: "a.b.c" -> baseVar="a", rest=".b.c"
+          baseVar = sourcePath.slice(0, dotIndex);
+          rest = sourcePath.slice(dotIndex); // includes the leading dot
+        } else {
+          // Path is a simple identifier: "currentEntityAnalysis" -> baseVar="currentEntityAnalysis", rest=""
+          baseVar = sourcePath;
+          rest = '';
+        }
+
+        if (baseVar in equivalentSignatureVariables && baseVar !== varName) {
+          const baseResolved = equivalentSignatureVariables[baseVar];
+          // If the base resolves to a hook call, add .functionCallReturnValue
+          if (baseResolved.endsWith('()')) {
+            const newPath = baseResolved + '.functionCallReturnValue' + rest;
+            if (newPath !== equivalentSignatureVariables[varName]) {
+              equivalentSignatureVariables[varName] = newPath;
+              changed = true;
+            }
+          } else if (baseResolved !== sourcePath) {
+            const newPath = baseResolved + rest;
+            if (newPath !== equivalentSignatureVariables[varName]) {
+              equivalentSignatureVariables[varName] = newPath;
+              changed = true;
+            }
+          }
+        }
       }
+
+      // Stop if no changes were made in this iteration
+      if (!changed) break;
     }
 
     return equivalentSignatureVariables;
@@ -2589,7 +4128,7 @@ export class ScopeDataStructure {
     final?: boolean,
   ): VariableInfo | undefined {
     const scopeNode = this.getScopeOrFunctionCallInfo(
-      scopeName ?? this.scopeTree.name,
+      scopeName ?? this.scopeTreeManager.getRootName(),
     );
     if (!scopeNode) return;
 
@@ -2626,11 +4165,16 @@ export class ScopeDataStructure {
     );
 
     const tempScopeNode = this.createTempScopeNode(
-      scopeName ?? this.scopeTree.name,
+      scopeName ?? this.scopeTreeManager.getRootName(),
       relevantSchema,
     );
 
+    // CRITICAL: Set onlyEquivalencies to true to prevent database modifications
+    // during this "getter" method. See comment in getFunctionSignature.
+    const wasOnlyEquivalencies = this.onlyEquivalencies;
+    this.onlyEquivalencies = true;
     this.validateSchema(tempScopeNode, true, final);
+    this.onlyEquivalencies = wasOnlyEquivalencies;
 
     return {
       name: variableName,
@@ -2639,98 +4183,1414 @@ export class ScopeDataStructure {
     };
   }
 
-  getExternalFunctionCalls() {
-    return this.externalFunctionCalls;
+  getExternalFunctionCalls(): FunctionCallInfo[] {
+    // Replace cyScope placeholders in all external function call data
+    // This ensures call signatures and schema paths use actual callback text
+    // instead of internal cyScope names, preventing mock data merge conflicts.
+    return this.externalFunctionCalls.map((efc) =>
+      this.cleanCyScopeFromFunctionCallInfo(efc),
+    );
   }
 
-  getEnvironmentVariables() {
-    return this.environmentVariables;
-  }
+  /**
+   * Cleans cyScope placeholder references from a FunctionCallInfo.
+   * Replaces cyScopeN() with the actual callback text in:
+   * - callSignature
+   * - allCallSignatures
+   * - schema keys
+   */
+  private cleanCyScopeFromFunctionCallInfo(
+    efc: FunctionCallInfo,
+  ): FunctionCallInfo {
+    const cyScopePattern = /cyScope\d+\(\)/g;
+
+    // Check if any cleaning is needed
+    const hasCyScope =
+      cyScopePattern.test(efc.callSignature) ||
+      (efc.allCallSignatures &&
+        efc.allCallSignatures.some((sig) => /cyScope\d+\(\)/.test(sig))) ||
+      (efc.schema &&
+        Object.keys(efc.schema).some((key) => /cyScope\d+\(\)/.test(key)));
+
+    if (!hasCyScope) {
+      return efc;
+    }
 
-  toSerializable(): SerializableDataStructure {
-    // Helper to convert ScopeVariable to SerializableScopeVariable
-    const toSerializableVariable = (
-      vars:
-        | ScopeVariable[]
-        | Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[],
-    ): SerializableScopeVariable[] =>
-      vars.map((v) => ({
-        scopeNodeName: v.scopeNodeName,
-        schemaPath: v.schemaPath,
-      }));
+    // Create cleaned copy
+    const cleaned: FunctionCallInfo = { ...efc };
 
-    // Helper to get function result for a given function name
-    const getFunctionResult = (
-      functionName?: string,
-    ): SerializableFunctionResult => {
-      return {
-        signature: this.getFunctionSignature({ functionName }) ?? {},
-        signatureWithUnknowns:
-          this.getFunctionSignature({ functionName, fillInUnknowns: true }) ??
-          {},
-        returnValue: this.getReturnValue({ functionName }) ?? {},
-        returnValueWithUnknowns:
-          this.getReturnValue({ functionName, fillInUnknowns: true }) ?? {},
-        usageEquivalencies: Object.entries(
-          this.getUsageEquivalencies(functionName) ?? {},
-        ).reduce(
-          (acc, [key, vars]) => {
-            acc[key] = toSerializableVariable(vars);
-            return acc;
-          },
-          {} as Record<string, SerializableScopeVariable[]>,
-        ),
-        sourceEquivalencies: Object.entries(
-          this.getSourceEquivalencies(functionName) ?? {},
-        ).reduce(
-          (acc, [key, vars]) => {
-            acc[key] = toSerializableVariable(vars);
-            return acc;
-          },
-          {} as Record<string, SerializableScopeVariable[]>,
-        ),
-        environmentVariables: this.getEnvironmentVariables(),
-      };
-    };
+    // Clean callSignature
+    cleaned.callSignature = this.replaceCyScopeInString(efc.callSignature);
 
-    // Convert external function calls
-    const externalFunctionCalls: SerializableFunctionCallInfo[] =
-      this.externalFunctionCalls.map((efc) => ({
-        name: efc.name,
-        callSignature: efc.callSignature,
-        callScope: efc.callScope,
-        schema: efc.schema,
-        equivalencies: efc.equivalencies
-          ? Object.entries(efc.equivalencies).reduce(
-              (acc, [key, vars]) => {
-                acc[key] = toSerializableVariable(vars);
-                return acc;
-              },
-              {} as Record<string, SerializableScopeVariable[]>,
-            )
-          : undefined,
-      }));
+    // Clean allCallSignatures
+    if (efc.allCallSignatures) {
+      cleaned.allCallSignatures = efc.allCallSignatures.map((sig) =>
+        this.replaceCyScopeInString(sig),
+      );
+    }
 
-    // Get root function result
-    const rootFunction = getFunctionResult();
+    // Clean schema keys
+    if (efc.schema) {
+      cleaned.schema = this.replaceCyScopePlaceholders(efc.schema);
+    }
 
-    // Get results for each external function
-    const functionResults: Record<string, SerializableFunctionResult> = {};
-    for (const efc of this.externalFunctionCalls) {
-      functionResults[efc.name] = getFunctionResult(efc.name);
+    // Clean callSignatureToVariable keys
+    if (efc.callSignatureToVariable) {
+      cleaned.callSignatureToVariable = Object.entries(
+        efc.callSignatureToVariable,
+      ).reduce(
+        (acc, [key, value]) => {
+          acc[this.replaceCyScopeInString(key)] = value;
+          return acc;
+        },
+        {} as Record<string, string>,
+      );
     }
 
-    // Get equivalent signature variables
-    const equivalentSignatureVariables = this.getEquivalentSignatureVariables();
+    return cleaned;
+  }
 
-    const environmentVariables = this.getEnvironmentVariables();
+  /**
+   * Replaces cyScope placeholder references in a single string.
+   * If the scope text can't be found, uses a generic fallback to avoid leaking
+   * internal cyScope names into stored data.
+   *
+   * Handles two patterns:
+   * 1. Function call style: cyScope7() - matched by cyScope(\d+)\(\)
+   * 2. Scope name style: parentName____cyScopeXX or cyScopeXX - matched by (\w+____)?cyScope([0-9A-Fa-f]+)
+   */
+  private replaceCyScopeInString(str: string): string {
+    let result = str;
+
+    // Pattern 1: Function call style - cyScope7()
+    const functionCallPattern = /cyScope(\d+)\(\)/g;
+    const functionCallMatches = [...str.matchAll(functionCallPattern)];
+    for (const match of functionCallMatches) {
+      const cyScopeName = `cyScope${match[1]}`;
+      const scopeText = this.findCyScopeText(cyScopeName);
+      // Always replace cyScope references - use actual text if available,
+      // otherwise use a generic callback placeholder
+      const replacement = scopeText || '() => {}';
+      result = result.replace(match[0], replacement);
+    }
 
-    return {
+    // Pattern 2: Scope name style - parentName____cyScopeXX or just cyScopeXX
+    // This handles hex-encoded scope IDs like cyScope1F
+    const scopeNamePattern = /(\w+____)?cyScope([0-9A-Fa-f]+)/g;
+    const scopeNameMatches = [...result.matchAll(scopeNamePattern)];
+    for (const match of scopeNameMatches) {
+      const fullMatch = match[0];
+      const prefix = match[1] || ''; // e.g., "getTitleColor____"
+      const cyScopeId = match[2]; // e.g., "1F"
+      const cyScopeName = `cyScope${cyScopeId}`;
+
+      // Try to find the scope text, checking both with and without prefix
+      let scopeText = this.findCyScopeText(cyScopeName);
+      if (!scopeText && prefix) {
+        // Try looking up with the full prefixed name
+        scopeText = this.findCyScopeText(`${prefix}${cyScopeName}`);
+      }
+
+      if (scopeText) {
+        result = result.replace(fullMatch, scopeText);
+      } else {
+        // Replace with a generic identifier to avoid leaking internal names
+        result = result.replace(fullMatch, 'callback');
+      }
+    }
+
+    return result;
+  }
+
+  getEnvironmentVariables() {
+    return this.environmentVariables;
+  }
+
+  /**
+   * Add conditional usages from AST analysis.
+   * Called during scope analysis to collect all conditionals.
+   */
+  addConditionalUsages(
+    usages: Record<
+      string,
+      Array<{
+        path: string;
+        conditionType: 'truthiness' | 'comparison' | 'switch';
+        comparedValues?: string[];
+        location: 'if' | 'ternary' | 'logical-and' | 'switch';
+      }>
+    >,
+  ): void {
+    for (const [path, pathUsages] of Object.entries(usages)) {
+      if (!this.rawConditionalUsages[path]) {
+        this.rawConditionalUsages[path] = [];
+      }
+      // Deduplicate usages
+      for (const usage of pathUsages) {
+        const exists = this.rawConditionalUsages[path].some(
+          (existing) =>
+            existing.location === usage.location &&
+            existing.conditionType === usage.conditionType &&
+            JSON.stringify(existing.comparedValues) ===
+              JSON.stringify(usage.comparedValues),
+        );
+        if (!exists) {
+          this.rawConditionalUsages[path].push(usage);
+        }
+      }
+    }
+  }
+
+  /**
+   * Add conditional effects from AST analysis.
+   * Called during scope analysis to collect all setter calls inside conditionals.
+   */
+  addConditionalEffects(
+    effects: import('../astScopes/types').ConditionalEffect[],
+  ): void {
+    // Add effects, avoiding duplicates based on effect stateVariable and condition paths
+    for (const effect of effects) {
+      const exists = this.rawConditionalEffects.some((existing) => {
+        // Same effect target (stateVariable + value)
+        const sameEffect =
+          existing.effect.stateVariable === effect.effect.stateVariable &&
+          existing.effect.value === effect.effect.value;
+        if (!sameEffect) return false;
+
+        // Same condition(s)
+        if (existing.condition && effect.condition) {
+          return (
+            existing.condition.path === effect.condition.path &&
+            existing.condition.requiredValue === effect.condition.requiredValue
+          );
+        }
+        if (existing.conditions && effect.conditions) {
+          if (existing.conditions.length !== effect.conditions.length)
+            return false;
+          return existing.conditions.every((ec, i) => {
+            const newCond = effect.conditions![i];
+            return (
+              ec.path === newCond.path &&
+              ec.requiredValue === newCond.requiredValue
+            );
+          });
+        }
+        return false;
+      });
+      if (!exists) {
+        this.rawConditionalEffects.push(effect);
+      }
+    }
+  }
+
+  /**
+   * Get conditional effects collected during analysis.
+   */
+  getConditionalEffects(): import('../astScopes/types').ConditionalEffect[] {
+    return this.rawConditionalEffects;
+  }
+
+  /**
+   * Add compound conditionals from AST analysis.
+   * Called during scope analysis to collect grouped conditions (e.g., a && b && c).
+   */
+  addCompoundConditionals(
+    compounds: import('../astScopes/types').CompoundConditional[],
+  ): void {
+    // Add compounds, avoiding duplicates based on chainId
+    for (const compound of compounds) {
+      const exists = this.rawCompoundConditionals.some(
+        (existing) => existing.chainId === compound.chainId,
+      );
+      if (!exists) {
+        this.rawCompoundConditionals.push(compound);
+      }
+    }
+  }
+
+  /**
+   * Get compound conditionals collected during analysis.
+   */
+  getCompoundConditionals(): import('../astScopes/types').CompoundConditional[] {
+    return this.rawCompoundConditionals;
+  }
+
+  /**
+   * Add child boundary gating conditions from AST analysis.
+   * These track which conditions must be true for a child component to render.
+   */
+  addChildBoundaryGatingConditions(
+    conditions: Record<string, import('../astScopes/types').ConditionalUsage[]>,
+  ): void {
+    for (const [childName, usages] of Object.entries(conditions)) {
+      if (!this.rawChildBoundaryGatingConditions[childName]) {
+        this.rawChildBoundaryGatingConditions[childName] = [];
+      }
+      // Add usages, avoiding duplicates
+      for (const usage of usages) {
+        const exists = this.rawChildBoundaryGatingConditions[childName].some(
+          (existing) =>
+            existing.path === usage.path &&
+            existing.conditionType === usage.conditionType &&
+            existing.isNegated === usage.isNegated,
+        );
+        if (!exists) {
+          this.rawChildBoundaryGatingConditions[childName].push(usage);
+        }
+      }
+    }
+  }
+
+  /**
+   * Get enriched child boundary gating conditions with source tracing.
+   * Similar to getEnrichedConditionalUsages but for gating conditions.
+   */
+  getEnrichedChildBoundaryGatingConditions(): Record<
+    string,
+    EnrichedConditionalUsage[]
+  > {
+    const enriched: Record<string, EnrichedConditionalUsage[]> = {};
+    const rootScopeName = this.scopeTreeManager.getTree().name;
+
+    for (const [childName, usages] of Object.entries(
+      this.rawChildBoundaryGatingConditions,
+    )) {
+      enriched[childName] = usages.map((usage) => {
+        // Try to trace this path back to a data source
+        const explanation = this.explainPath(rootScopeName, usage.path);
+
+        let sourceDataPath: string | undefined;
+        if (explanation.source) {
+          sourceDataPath = `${explanation.source.scope}.${explanation.source.path}`;
+        }
+
+        return {
+          ...usage,
+          sourceDataPath,
+        };
+      });
+    }
+
+    return enriched;
+  }
+
+  /**
+   * Get enriched conditional usages with source tracing.
+   * Uses explainPath to trace each local variable back to its data source.
+   * Preserves all fields from the raw conditional usages including derivedFrom.
+   */
+  getEnrichedConditionalUsages(): Record<string, EnrichedConditionalUsage[]> {
+    const enriched: Record<string, EnrichedConditionalUsage[]> = {};
+
+    for (const [path, usages] of Object.entries(this.rawConditionalUsages)) {
+      // Try to trace this path back to a data source
+      // First, try the root scope
+      const rootScopeName = this.scopeTreeManager.getTree().name;
+      const explanation = this.explainPath(rootScopeName, path);
+
+      let sourceDataPath: string | undefined;
+      if (explanation.source) {
+        // Build the full data path: scopeName.path
+        sourceDataPath = `${explanation.source.scope}.${explanation.source.path}`;
+      }
+
+      enriched[path] = usages.map((usage) => ({
+        ...usage,
+        sourceDataPath,
+      }));
+    }
+
+    return enriched;
+  }
+
+  toSerializable(): SerializableDataStructure {
+    // Helper to clean cyScope and cyDuplicateKey from a string for output
+    const cleanCyScope = (str: string): string =>
+      this.replaceCyScopeInString(str).replace(/::cyDuplicateKey\d+::/g, '');
+
+    // Helper to convert ScopeVariable to SerializableScopeVariable (with cyScope cleaned)
+    const toSerializableVariable = (
+      vars:
+        | ScopeVariable[]
+        | Pick<ScopeVariable, 'scopeNodeName' | 'schemaPath'>[],
+    ): SerializableScopeVariable[] =>
+      vars.map((v) => ({
+        scopeNodeName: cleanCyScope(v.scopeNodeName),
+        schemaPath: cleanCyScope(v.schemaPath),
+      }));
+
+    // Helper to clean cyScope from all keys in a schema
+    const cleanSchemaKeys = (
+      schema: Record<string, string>,
+    ): Record<string, string> => {
+      return Object.entries(schema).reduce(
+        (acc, [key, value]) => {
+          acc[cleanCyScope(key)] = value;
+          return acc;
+        },
+        {} as Record<string, string>,
+      );
+    };
+
+    // Helper to get function result for a given function name
+    const getFunctionResult = (
+      functionName?: string,
+    ): SerializableFunctionResult => {
+      return {
+        signature: cleanSchemaKeys(
+          this.getFunctionSignature({ functionName }) ?? {},
+        ),
+        signatureWithUnknowns: cleanSchemaKeys(
+          this.getFunctionSignature({ functionName, fillInUnknowns: true }) ??
+            {},
+        ),
+        returnValue: cleanSchemaKeys(
+          this.getReturnValue({ functionName }) ?? {},
+        ),
+        returnValueWithUnknowns: cleanSchemaKeys(
+          this.getReturnValue({ functionName, fillInUnknowns: true }) ?? {},
+        ),
+        usageEquivalencies: Object.entries(
+          this.getUsageEquivalencies(functionName) ?? {},
+        ).reduce(
+          (acc, [key, vars]) => {
+            // Clean cyScope from the key as well as variable properties
+            acc[cleanCyScope(key)] = toSerializableVariable(vars);
+            return acc;
+          },
+          {} as Record<string, SerializableScopeVariable[]>,
+        ),
+        sourceEquivalencies: Object.entries(
+          this.getSourceEquivalencies(functionName) ?? {},
+        ).reduce(
+          (acc, [key, vars]) => {
+            // Clean cyScope from the key as well as variable properties
+            acc[cleanCyScope(key)] = toSerializableVariable(vars);
+            return acc;
+          },
+          {} as Record<string, SerializableScopeVariable[]>,
+        ),
+        environmentVariables: this.getEnvironmentVariables(),
+      };
+    };
+
+    // Convert external function calls - use getExternalFunctionCalls() which cleans cyScope
+    const cleanedExternalCalls = this.getExternalFunctionCalls();
+
+    // Get root scope schema for building per-variable return value schemas
+    const rootScopeName = this.scopeTreeManager.getRootName();
+    const rootScope = this.scopeNodes[rootScopeName];
+    const rootSchema = rootScope?.schema ?? {};
+
+    const externalFunctionCalls: SerializableFunctionCallInfo[] =
+      cleanedExternalCalls.map((efc) => {
+        // Build perVariableSchemas from perCallSignatureSchemas when available.
+        // This preserves distinct schemas per variable when the same function is called
+        // multiple times with DIFFERENT call signatures (e.g., different type parameters).
+        //
+        // When field accesses happen in child scopes (like JSX expressions), the
+        // rootSchema doesn't contain the detailed paths - they end up in child scope
+        // schemas. Using perCallSignatureSchemas ensures we get the correct schema
+        // for each call, regardless of where field accesses occur.
+        let perVariableSchemas:
+          | Record<string, Record<string, string>>
+          | undefined;
+
+        // Use perCallSignatureSchemas only when:
+        // 1. It exists and has distinct entries for different call signatures
+        // 2. The number of distinct call signatures >= number of receiving variables
+        //
+        // This prevents using it when all calls have the same signature (e.g., useFetcher() x 2)
+        // because in that case, perCallSignatureSchemas only has one entry.
+        const numCallSignatures = efc.perCallSignatureSchemas
+          ? Object.keys(efc.perCallSignatureSchemas).length
+          : 0;
+        const numReceivingVars = efc.receivingVariableNames?.length ?? 0;
+        const hasDistinctSchemas =
+          numCallSignatures >= numReceivingVars && numCallSignatures > 1;
+
+        // CASE 1: Multiple call signatures with distinct schemas - use indexed variable names
+        if (
+          hasDistinctSchemas &&
+          efc.perCallSignatureSchemas &&
+          efc.callSignatureToVariable
+        ) {
+          perVariableSchemas = {};
+
+          // Build a reverse map: variable -> array of call signatures (in order)
+          // This handles the case where the same variable name is reused for different calls
+          const varToCallSigs: Record<string, string[]> = {};
+          for (const [callSig, varName] of Object.entries(
+            efc.callSignatureToVariable,
+          )) {
+            if (!varToCallSigs[varName]) {
+              varToCallSigs[varName] = [];
+            }
+            varToCallSigs[varName].push(callSig);
+          }
+
+          // Track how many times each variable name has been seen
+          const varNameCounts: Record<string, number> = {};
+
+          // For each receiving variable, get its original schema from perCallSignatureSchemas
+          for (const varName of efc.receivingVariableNames ?? []) {
+            const occurrence = varNameCounts[varName] ?? 0;
+            varNameCounts[varName] = occurrence + 1;
+
+            const callSigs = varToCallSigs[varName];
+            // Use the nth call signature for the nth occurrence of this variable
+            const callSig = callSigs?.[occurrence];
+
+            if (callSig && efc.perCallSignatureSchemas[callSig]) {
+              // Use indexed key if this variable name is reused (e.g., fetcher, fetcher[1])
+              const key =
+                occurrence === 0 ? varName : `${varName}[${occurrence}]`;
+              // Clone the schema to avoid shared references
+              perVariableSchemas[key] = {
+                ...efc.perCallSignatureSchemas[callSig],
+              };
+            }
+          }
+
+          // Only include if we have entries for ALL receiving variables
+          if (Object.keys(perVariableSchemas).length < numReceivingVars) {
+            // Not all variables have schemas - fall back to rootSchema extraction
+            perVariableSchemas = undefined;
+          } else {
+            // Also check that at least one schema is non-empty
+            // Bug fix: perCallSignatureSchemas may have entries but with empty schemas {}
+            // In this case, we should fall through to Fallback which uses rootSchema
+            const hasNonEmptySchema = Object.values(perVariableSchemas).some(
+              (schema) => Object.keys(schema).length > 0,
+            );
+            if (!hasNonEmptySchema) {
+              perVariableSchemas = undefined;
+            }
+          }
+        }
+
+        // CASE 2: Single call signature with single variable - use perCallSignatureSchemas directly
+        // This handles parameterized calls like useFetcher<ConfigData>() where each is a separate efc entry
+        if (
+          !perVariableSchemas &&
+          efc.perCallSignatureSchemas &&
+          numCallSignatures === 1 &&
+          numReceivingVars === 1
+        ) {
+          const varName = efc.receivingVariableNames![0];
+          const callSig = Object.keys(efc.perCallSignatureSchemas)[0];
+          const schema = efc.perCallSignatureSchemas[callSig];
+          if (schema && Object.keys(schema).length > 0) {
+            perVariableSchemas = { [varName]: { ...schema } };
+          }
+        }
+
+        // CASE 3: Extract from efc.schema when perCallSignatureSchemas is missing or empty
+        // This handles two scenarios:
+        // 1. Parameterized calls that create SEPARATE efc entries (no perCallSignatureSchemas)
+        // 2. Destructuring where perCallSignatureSchemas exists but has EMPTY schemas
+        //
+        // When useFetcher<ConfigData>() and useFetcher<SettingsData>() are called, they create separate
+        // efc entries because getFunctionCallRoot preserves type parameters. Each entry has its own
+        // `schema` field, but due to variable reassignment, the schema may be contaminated with paths
+        // from other calls (the tracer attributes field accesses to ALL equivalencies).
+        //
+        // Solution: Filter efc.schema to only include paths that match THIS entry's call signature.
+        // The schema paths include the full call signature prefix, so we can filter by it.
+        //
+        // Example: ConfigData entry has paths like:
+        //   "useFetcher<{ data: ConfigData | null }>().functionCallReturnValue.data.data.theme"
+        // But also (contaminated):
+        //   "useFetcher<{ data: ConfigData | null }>().functionCallReturnValue.data.data.notifications"
+        //
+        // We filter to only keep paths that should belong to THIS call by checking if the
+        // receiving variable's equivalency points to this call's return value.
+        //
+        // BUG FIX: The old condition `!efc.perCallSignatureSchemas` was FALSE when the object
+        // existed (even with empty schemas), causing this case to be skipped. We now also check
+        // if all schemas in perCallSignatureSchemas are empty.
+        const hasNonEmptyPerCallSignatureSchemas =
+          efc.perCallSignatureSchemas &&
+          Object.values(efc.perCallSignatureSchemas).some(
+            (schema) => Object.keys(schema).length > 0,
+          );
+
+        // Build the call signature prefix that paths should start with
+        const callSigPrefix = `${efc.callSignature}.functionCallReturnValue`;
+
+        // Check if efc.schema has variable-specific paths (indicating destructuring).
+        // Destructuring: const { entities, gitStatus } = useLoaderData()
+        // - efc.schema has paths like: useLoaderData().functionCallReturnValue.entities...
+        // Multiple calls: const x = useFetcher(); const y = useFetcher();
+        // - efc.schema has paths like: useFetcher().functionCallReturnValue.data...
+        // CASE 3 should only run for destructuring (variable-specific paths exist).
+        const hasVariableSpecificPaths = (
+          efc.receivingVariableNames ?? []
+        ).some((varName) =>
+          Object.keys(efc.schema).some((path) =>
+            path.startsWith(`${callSigPrefix}.${varName}`),
+          ),
+        );
+
+        if (
+          !perVariableSchemas &&
+          !hasNonEmptyPerCallSignatureSchemas &&
+          numReceivingVars >= 1 &&
+          hasVariableSpecificPaths
+        ) {
+          // Filter efc.schema to only include paths matching this call signature
+          const filteredSchema: Record<string, string> = {};
+          for (const [path, type] of Object.entries(efc.schema)) {
+            if (path.startsWith(callSigPrefix) || path === efc.callSignature) {
+              filteredSchema[path] = type;
+            }
+          }
+
+          // Build perVariableSchemas from the filtered schema
+          // For destructuring, filter paths by variable name
+          if (Object.keys(filteredSchema).length > 0) {
+            perVariableSchemas = {};
+            for (const varName of efc.receivingVariableNames ?? []) {
+              // For destructuring, extract only paths specific to this variable
+              const varSpecificPrefix = `${callSigPrefix}.${varName}`;
+              const varSchema: Record<string, string> = {};
+
+              for (const [path, type] of Object.entries(filteredSchema)) {
+                if (path.startsWith(varSpecificPrefix)) {
+                  // Transform: useLoaderData().functionCallReturnValue.entities.sha
+                  //         -> functionCallReturnValue.entities.sha (keep the variable name)
+                  const suffix = path.slice(callSigPrefix.length);
+                  const returnValuePath = `functionCallReturnValue${suffix}`;
+                  varSchema[returnValuePath] = type;
+                } else if (path === efc.callSignature) {
+                  // Include the function call type itself
+                  varSchema[path] = type;
+                }
+              }
+              if (Object.keys(varSchema).length > 0) {
+                perVariableSchemas[varName] = varSchema;
+              }
+            }
+            // Only include if we have entries
+            if (Object.keys(perVariableSchemas).length === 0) {
+              perVariableSchemas = undefined;
+            }
+          }
+        }
+
+        // Fallback: extract from root scope schema when perCallSignatureSchemas is not available
+        // or doesn't have distinct entries for each variable.
+        // This works when field accesses are in the root scope.
+        if (
+          !perVariableSchemas &&
+          efc.receivingVariableNames &&
+          efc.receivingVariableNames.length > 0
+        ) {
+          perVariableSchemas = {};
+          for (const varName of efc.receivingVariableNames) {
+            const varSchema: Record<string, string> = {};
+            for (const [path, type] of Object.entries(rootSchema)) {
+              // Check if path starts with this variable name
+              if (
+                path === varName ||
+                path.startsWith(varName + '.') ||
+                path.startsWith(varName + '[')
+              ) {
+                // Transform to functionCallReturnValue format
+                // e.g., userFetcher.data.id -> functionCallReturnValue.data.id
+                const suffix = path.slice(varName.length);
+                const returnValuePath = `functionCallReturnValue${suffix}`;
+                varSchema[returnValuePath] = type;
+              }
+            }
+            if (Object.keys(varSchema).length > 0) {
+              // Clean the variable name when using as key in output
+              perVariableSchemas[cleanCyScope(varName)] = varSchema;
+            }
+          }
+          // Only include if we have any entries
+          if (Object.keys(perVariableSchemas).length === 0) {
+            perVariableSchemas = undefined;
+          }
+        }
+
+        return {
+          name: efc.name,
+          callSignature: efc.callSignature,
+          callScope: efc.callScope,
+          schema: efc.schema,
+          equivalencies: efc.equivalencies
+            ? Object.entries(efc.equivalencies).reduce(
+                (acc, [key, vars]) => {
+                  // Clean cyScope from the key as well as variable properties
+                  acc[cleanCyScope(key)] = toSerializableVariable(vars);
+                  return acc;
+                },
+                {} as Record<string, SerializableScopeVariable[]>,
+              )
+            : undefined,
+          allCallSignatures: efc.allCallSignatures,
+          receivingVariableNames: efc.receivingVariableNames?.map(cleanCyScope),
+          callSignatureToVariable: efc.callSignatureToVariable
+            ? Object.fromEntries(
+                Object.entries(efc.callSignatureToVariable).map(([k, v]) => [
+                  k,
+                  cleanCyScope(v),
+                ]),
+              )
+            : undefined,
+          perVariableSchemas,
+        };
+      });
+
+    // POST-PROCESSING: Deduplicate schemas across parameterized calls to same base function
+    // When useFetcher<ConfigData>() and useFetcher<SettingsData>() are called, they create
+    // separate entries. Due to variable reassignment, BOTH entries may have ALL fields.
+    // We deduplicate by assigning each field to ONLY ONE entry based on order of appearance.
+    //
+    // Strategy: Fields that appear first in order belong to the first entry,
+    // fields that appear later belong to later entries (split evenly).
+    const deduplicateParameterizedEntries = (
+      entries: typeof externalFunctionCalls,
+    ): typeof externalFunctionCalls => {
+      // Group entries by base function name (without type parameters)
+      const groups = new Map<string, typeof externalFunctionCalls>();
+      for (const entry of entries) {
+        // Extract base function name by stripping type parameters
+        // e.g., "useFetcher<{ data: ConfigData | null }>" -> "useFetcher"
+        const baseName = entry.name.replace(/<.*>$/, '');
+        const group = groups.get(baseName) || [];
+        group.push(entry);
+        groups.set(baseName, group);
+      }
+
+      // Process groups with multiple parameterized entries
+      for (const [, group] of groups) {
+        if (group.length <= 1) continue;
+
+        // Check if these are parameterized calls (have type parameters in name)
+        const hasTypeParams = group.every((e) => e.name.includes('<'));
+        if (!hasTypeParams) continue;
+
+        // Collect ALL unique field suffixes across all entries (in order of first appearance)
+        // Field suffix is the path after functionCallReturnValue, e.g., ".data.data.theme"
+        const allFieldSuffixes: string[] = [];
+        for (const entry of group) {
+          if (!entry.perVariableSchemas) continue;
+          for (const varSchema of Object.values(entry.perVariableSchemas)) {
+            for (const path of Object.keys(varSchema)) {
+              // Skip the base "functionCallReturnValue" entry
+              if (path === 'functionCallReturnValue') continue;
+              // Extract field suffix
+              const match = path.match(/functionCallReturnValue(.+)/);
+              if (!match) continue;
+              const fieldSuffix = match[1];
+              if (!allFieldSuffixes.includes(fieldSuffix)) {
+                allFieldSuffixes.push(fieldSuffix);
+              }
+            }
+          }
+        }
+
+        // Assign fields to entries: split evenly based on order
+        // First N/2 fields go to first entry, remaining go to second entry
+        const fieldToEntryMap = new Map<string, number>();
+        const fieldsPerEntry = Math.ceil(
+          allFieldSuffixes.length / group.length,
+        );
+        for (let i = 0; i < allFieldSuffixes.length; i++) {
+          const fieldSuffix = allFieldSuffixes[i];
+          const entryIdx = Math.min(
+            Math.floor(i / fieldsPerEntry),
+            group.length - 1,
+          );
+          fieldToEntryMap.set(fieldSuffix, entryIdx);
+        }
+
+        // Filter each entry's perVariableSchemas to only include its assigned fields
+        for (let i = 0; i < group.length; i++) {
+          const entry = group[i];
+          if (!entry.perVariableSchemas) continue;
+
+          const filteredPerVarSchemas: Record<
+            string,
+            Record<string, string>
+          > = {};
+          for (const [varName, varSchema] of Object.entries(
+            entry.perVariableSchemas,
+          )) {
+            const filteredVarSchema: Record<string, string> = {};
+            for (const [path, type] of Object.entries(varSchema)) {
+              // Always keep the base functionCallReturnValue
+              if (path === 'functionCallReturnValue') {
+                filteredVarSchema[path] = type;
+                continue;
+              }
+              // Extract field suffix
+              const match = path.match(/functionCallReturnValue(.+)/);
+              if (!match) {
+                // Keep non-field paths
+                filteredVarSchema[path] = type;
+                continue;
+              }
+              const fieldSuffix = match[1];
+              // Only include if this entry owns this field
+              if (fieldToEntryMap.get(fieldSuffix) === i) {
+                filteredVarSchema[path] = type;
+              }
+            }
+            if (Object.keys(filteredVarSchema).length > 0) {
+              filteredPerVarSchemas[varName] = filteredVarSchema;
+            }
+          }
+          entry.perVariableSchemas =
+            Object.keys(filteredPerVarSchemas).length > 0
+              ? filteredPerVarSchemas
+              : undefined;
+        }
+      }
+
+      return entries;
+    };
+
+    // Apply deduplication
+    const deduplicatedExternalFunctionCalls = deduplicateParameterizedEntries(
       externalFunctionCalls,
+    );
+
+    // IMPORTANT: Get equivalent signature variables BEFORE calling getFunctionResult
+    // because getFunctionResult calls validateSchema which may remove equivalencies
+    // during the finalize step (e.g., cleanNonObjectFunctions removes method call
+    // equivalencies like `segments -> splat.split('/').functionCallReturnValue`).
+    // Fix 33: Move this call before any schema validation to preserve method call chains.
+    const equivalentSignatureVariables = this.getEquivalentSignatureVariables();
+
+    // Get root function result
+    const rootFunction = getFunctionResult();
+
+    // Get results for each external function (use cleaned calls for consistency)
+    const functionResults: Record<string, SerializableFunctionResult> = {};
+    for (const efc of cleanedExternalCalls) {
+      functionResults[efc.name] = getFunctionResult(efc.name);
+    }
+
+    const environmentVariables = this.getEnvironmentVariables();
+
+    // Get enriched conditional usages with source tracing
+    const enrichedConditionalUsages = this.getEnrichedConditionalUsages();
+    const conditionalUsages =
+      Object.keys(enrichedConditionalUsages).length > 0
+        ? enrichedConditionalUsages
+        : undefined;
+
+    // Get conditional effects (setter calls inside conditionals)
+    const conditionalEffects =
+      this.rawConditionalEffects.length > 0
+        ? this.rawConditionalEffects
+        : undefined;
+
+    // Get compound conditionals (grouped conditions that must all be true)
+    const compoundConditionals =
+      this.rawCompoundConditionals.length > 0
+        ? this.rawCompoundConditionals
+        : undefined;
+
+    // Get child boundary gating conditions
+    const enrichedGatingConditions =
+      this.getEnrichedChildBoundaryGatingConditions();
+    const childBoundaryGatingConditions =
+      Object.keys(enrichedGatingConditions).length > 0
+        ? enrichedGatingConditions
+        : undefined;
+
+    return {
+      externalFunctionCalls: deduplicatedExternalFunctionCalls,
       rootFunction,
       functionResults,
       equivalentSignatureVariables,
       environmentVariables,
+      conditionalUsages,
+      conditionalEffects,
+      compoundConditionals,
+      childBoundaryGatingConditions,
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // DEBUGGING HELPERS
+  // These methods help understand what's happening during analysis.
+  // Use them when investigating why a path is missing or has the wrong type.
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Explains a path by tracing its equivalencies and showing where data comes from.
+   *
+   * @example
+   * ```typescript
+   * const explanation = sds.explainPath('MyComponent', 'user.id');
+   * console.log(explanation);
+   * // {
+   * //   path: 'user.id',
+   * //   scope: 'MyComponent',
+   * //   schemaValue: 'string',
+   * //   equivalencies: [
+   * //     { scope: 'MyComponent', path: 'signature[0].user.id' },
+   * //     { scope: 'UserProfile', path: 'props.user.id' }
+   * //   ],
+   * //   source: { scope: 'fetchUser', path: 'functionCallReturnValue(fetch).data.user.id' }
+   * // }
+   * ```
+   */
+  explainPath(
+    scopeName: string,
+    path: string,
+  ): {
+    path: string;
+    scope: string;
+    schemaValue: string | undefined;
+    equivalencies: Array<{ scope: string; path: string; reason?: string }>;
+    databaseEntry: EquivalencyDatabaseEntry | undefined;
+    source: { scope: string; path: string } | undefined;
+  } {
+    const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
+    if (!scopeNode) {
+      return {
+        path,
+        scope: scopeName,
+        schemaValue: undefined,
+        equivalencies: [],
+        databaseEntry: undefined,
+        source: undefined,
+      };
+    }
+
+    const schemaValue = scopeNode.schema?.[path];
+    const rawEquivalencies = scopeNode.equivalencies?.[path] ?? [];
+
+    const equivalencies = rawEquivalencies.map((eq) => ({
+      scope: eq.scopeNodeName,
+      path: eq.schemaPath,
+      reason: eq.equivalencyReason,
+    }));
+
+    const databaseEntry = this.getEquivalenciesDatabaseEntry(scopeName, path);
+    const source =
+      databaseEntry?.sourceCandidates?.[0] &&
+      databaseEntry.sourceCandidates.length > 0
+        ? {
+            scope: databaseEntry.sourceCandidates[0].scopeNodeName,
+            path: databaseEntry.sourceCandidates[0].schemaPath,
+          }
+        : undefined;
+
+    return {
+      path,
+      scope: scopeName,
+      schemaValue,
+      equivalencies,
+      databaseEntry,
+      source,
+    };
+  }
+
+  /**
+   * Dumps the current state of analysis for inspection.
+   * Useful for understanding the overall state or finding issues.
+   *
+   * @param options - What to include in the dump
+   * @returns A summary object with requested data
+   */
+  dumpState(options?: {
+    includeSchemas?: boolean;
+    includeEquivalencies?: boolean;
+    scopeFilter?: string;
+  }): {
+    scopeCount: number;
+    externalCallCount: number;
+    equivalencyDatabaseSize: number;
+    metrics: {
+      addToSchemaCallCount: number;
+      followEquivalenciesCallCount: number;
+      maxEquivalencyChainDepth: number;
+    };
+    scopes: Array<{
+      name: string;
+      schemaKeyCount: number;
+      equivalencyKeyCount: number;
+      functionCallCount: number;
+      schema?: Record<string, string>;
+      equivalencies?: Record<string, Array<{ scope: string; path: string }>>;
+    }>;
+  } {
+    const includeSchemas = options?.includeSchemas ?? false;
+    const includeEquivalencies = options?.includeEquivalencies ?? false;
+    const scopeFilter = options?.scopeFilter;
+
+    const scopeNames = Object.keys(this.scopeNodes).filter(
+      (name) => !scopeFilter || name.includes(scopeFilter),
+    );
+
+    const scopes = scopeNames.map((name) => {
+      const node = this.scopeNodes[name];
+      const result: {
+        name: string;
+        schemaKeyCount: number;
+        equivalencyKeyCount: number;
+        functionCallCount: number;
+        schema?: Record<string, string>;
+        equivalencies?: Record<string, Array<{ scope: string; path: string }>>;
+      } = {
+        name,
+        schemaKeyCount: Object.keys(node.schema ?? {}).length,
+        equivalencyKeyCount: Object.keys(node.equivalencies ?? {}).length,
+        functionCallCount: node.functionCalls?.length ?? 0,
+      };
+
+      if (includeSchemas) {
+        result.schema = node.schema;
+      }
+
+      if (includeEquivalencies) {
+        result.equivalencies = Object.entries(node.equivalencies ?? {}).reduce(
+          (acc, [key, vals]) => {
+            acc[key] = vals.map((v) => ({
+              scope: v.scopeNodeName,
+              path: v.schemaPath,
+            }));
+            return acc;
+          },
+          {} as Record<string, Array<{ scope: string; path: string }>>,
+        );
+      }
+
+      return result;
+    });
+
+    return {
+      scopeCount: Object.keys(this.scopeNodes).length,
+      externalCallCount: this.externalFunctionCalls.length,
+      equivalencyDatabaseSize: this.equivalencyDatabase.length,
+      metrics: {
+        addToSchemaCallCount,
+        followEquivalenciesCallCount,
+        maxEquivalencyChainDepth,
+      },
+      scopes,
+    };
+  }
+
+  /**
+   * Traces the full equivalency chain for a path, showing how data flows.
+   * This is the most detailed debugging tool for understanding data tracing.
+   *
+   * @example
+   * ```typescript
+   * const chain = sds.traceEquivalencyChain('MyComponent', 'user.id');
+   * // Returns array of steps showing how user.id is traced back to its source
+   * ```
+   */
+  traceEquivalencyChain(
+    scopeName: string,
+    path: string,
+    maxDepth = 20,
+  ): Array<{
+    step: number;
+    scope: string;
+    path: string;
+    schemaValue?: string;
+    nextEquivalencies: Array<{ scope: string; path: string; reason?: string }>;
+  }> {
+    const chain: Array<{
+      step: number;
+      scope: string;
+      path: string;
+      schemaValue?: string;
+      nextEquivalencies: Array<{
+        scope: string;
+        path: string;
+        reason?: string;
+      }>;
+    }> = [];
+
+    const visited = new Set<string>();
+    const queue: Array<{ scope: string; path: string; depth: number }> = [
+      { scope: scopeName, path, depth: 0 },
+    ];
+
+    while (queue.length > 0 && chain.length < maxDepth) {
+      const current = queue.shift()!;
+      const key = `${current.scope}::${current.path}`;
+
+      if (visited.has(key)) continue;
+      visited.add(key);
+
+      const scopeNode = this.getScopeOrFunctionCallInfo(current.scope);
+      const schemaValue = scopeNode?.schema?.[current.path];
+      const rawEquivalencies = scopeNode?.equivalencies?.[current.path] ?? [];
+
+      const nextEquivalencies = rawEquivalencies.map((eq) => ({
+        scope: eq.scopeNodeName,
+        path: eq.schemaPath,
+        reason: eq.equivalencyReason,
+      }));
+
+      chain.push({
+        step: chain.length + 1,
+        scope: current.scope,
+        path: current.path,
+        schemaValue,
+        nextEquivalencies,
+      });
+
+      // Add next equivalencies to queue for further tracing
+      for (const eq of nextEquivalencies) {
+        const nextKey = `${eq.scope}::${eq.path}`;
+        if (!visited.has(nextKey)) {
+          queue.push({
+            scope: eq.scope,
+            path: eq.path,
+            depth: current.depth + 1,
+          });
+        }
+      }
+    }
+
+    return chain;
+  }
+
+  /**
+   * Finds all paths in a scope that match a pattern.
+   * Useful for finding related paths when debugging.
+   *
+   * @example
+   * ```typescript
+   * const paths = sds.findPaths('MyComponent', /user/);
+   * // Returns all schema paths containing "user"
+   * ```
+   */
+  findPaths(
+    scopeName: string,
+    pattern: RegExp | string,
+  ): Array<{ path: string; value: string; hasEquivalencies: boolean }> {
+    const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
+    if (!scopeNode) return [];
+
+    const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+    const results: Array<{
+      path: string;
+      value: string;
+      hasEquivalencies: boolean;
+    }> = [];
+
+    // Search in schema
+    for (const [path, value] of Object.entries(scopeNode.schema ?? {})) {
+      if (regex.test(path)) {
+        results.push({
+          path,
+          value,
+          hasEquivalencies: !!scopeNode.equivalencies?.[path]?.length,
+        });
+      }
+    }
+
+    // Also search equivalency keys that might not be in schema
+    for (const path of Object.keys(scopeNode.equivalencies ?? {})) {
+      if (regex.test(path) && !results.find((r) => r.path === path)) {
+        results.push({
+          path,
+          value: scopeNode.schema?.[path] ?? 'not-in-schema',
+          hasEquivalencies: true,
+        });
+      }
+    }
+
+    return results.sort((a, b) => a.path.localeCompare(b.path));
+  }
+
+  /**
+   * Returns a summary of why a path might be missing from the schema.
+   * Checks common issues that cause paths to not appear.
+   */
+  diagnoseMissingPath(
+    scopeName: string,
+    path: string,
+  ): {
+    exists: boolean;
+    inSchema: boolean;
+    inEquivalencies: boolean;
+    possibleReasons: string[];
+    suggestions: string[];
+  } {
+    const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
+    const possibleReasons: string[] = [];
+    const suggestions: string[] = [];
+
+    if (!scopeNode) {
+      possibleReasons.push(`Scope "${scopeName}" does not exist`);
+      suggestions.push(
+        `Available scopes: ${Object.keys(this.scopeNodes).join(', ')}`,
+      );
+      return {
+        exists: false,
+        inSchema: false,
+        inEquivalencies: false,
+        possibleReasons,
+        suggestions,
+      };
+    }
+
+    const inSchema = path in (scopeNode.schema ?? {});
+    const inEquivalencies = path in (scopeNode.equivalencies ?? {});
+
+    if (inSchema) {
+      return {
+        exists: true,
+        inSchema: true,
+        inEquivalencies,
+        possibleReasons: [],
+        suggestions: [],
+      };
+    }
+
+    // Check for similar paths
+    const allPaths = [
+      ...Object.keys(scopeNode.schema ?? {}),
+      ...Object.keys(scopeNode.equivalencies ?? {}),
+    ];
+
+    const similarPaths = allPaths.filter((p) => {
+      const pathParts = path.split('.');
+      const pParts = p.split('.');
+      return (
+        pathParts.some((part) => pParts.includes(part)) ||
+        p.includes(path) ||
+        path.includes(p)
+      );
+    });
+
+    if (similarPaths.length > 0) {
+      possibleReasons.push(`Path "${path}" not found but similar paths exist`);
+      suggestions.push(`Similar paths: ${similarPaths.slice(0, 5).join(', ')}`);
+    }
+
+    // Check if it's a partial path
+    const parentPath = path.split('.').slice(0, -1).join('.');
+    if (parentPath && scopeNode.schema?.[parentPath]) {
+      possibleReasons.push(
+        `Parent path "${parentPath}" exists with value "${scopeNode.schema[parentPath]}"`,
+      );
+      suggestions.push(
+        `The property might not have been accessed in the analyzed code`,
+      );
+    }
+
+    // Check visited tracker
+    const wasVisited = this.visitedTracker.wasVisited(scopeName, path);
+    if (wasVisited) {
+      possibleReasons.push(`Path was visited during analysis but not written`);
+      suggestions.push(
+        `Check if the path was filtered by isValidPath() or hit cycle detection`,
+      );
+    }
+
+    if (possibleReasons.length === 0) {
+      possibleReasons.push(
+        `Path "${path}" was never encountered during analysis`,
+      );
+      suggestions.push(
+        `Verify the path is accessed in the source code being analyzed`,
+      );
+    }
+
+    return {
+      exists: false,
+      inSchema,
+      inEquivalencies,
+      possibleReasons,
+      suggestions,
     };
   }
+
+  /**
+   * Analyzes the stored equivalencies to provide aggregate statistics.
+   * Call this AFTER analysis completes to understand equivalency patterns.
+   *
+   * @example
+   * ```typescript
+   * const analysis = sds.analyzeEquivalencies();
+   * console.log(analysis.byReason); // Count by reason
+   * console.log(analysis.byScope);  // Count by scope
+   * console.log(analysis.hotSpots); // Scopes with most equivalencies
+   * ```
+   */
+  analyzeEquivalencies(): {
+    total: number;
+    byReason: Record<string, number>;
+    byScope: Record<string, number>;
+    hotSpots: Array<{ scope: string; count: number }>;
+    unusedReasons: string[];
+  } {
+    const byReason: Record<string, number> = {};
+    const byScope: Record<string, number> = {};
+    let total = 0;
+
+    // Collect from all scope nodes
+    for (const scopeName of Object.keys(this.scopeNodes)) {
+      const scopeNode = this.scopeNodes[scopeName];
+      const equivalencies = scopeNode.equivalencies ?? {};
+
+      for (const path of Object.keys(equivalencies)) {
+        for (const eq of equivalencies[path]) {
+          total++;
+          const reason = eq.equivalencyReason ?? 'unknown';
+          byReason[reason] = (byReason[reason] ?? 0) + 1;
+          byScope[scopeName] = (byScope[scopeName] ?? 0) + 1;
+        }
+      }
+    }
+
+    // Also check external function calls
+    for (const fc of this.externalFunctionCalls) {
+      const equivalencies = fc.equivalencies ?? {};
+      for (const path of Object.keys(equivalencies)) {
+        for (const eq of equivalencies[path]) {
+          total++;
+          const reason = eq.equivalencyReason ?? 'unknown';
+          byReason[reason] = (byReason[reason] ?? 0) + 1;
+          byScope[fc.name] = (byScope[fc.name] ?? 0) + 1;
+        }
+      }
+    }
+
+    // Find hot spots (scopes with most equivalencies)
+    const hotSpots = Object.entries(byScope)
+      .map(([scope, count]) => ({ scope, count }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 10);
+
+    // Find reasons that appear in stored equivalencies but aren't in ALLOWED list
+    const unusedReasons = Object.keys(byReason).filter(
+      (reason) => !ALLOWED_EQUIVALENCY_REASONS.has(reason),
+    );
+
+    return {
+      total,
+      byReason,
+      byScope,
+      hotSpots,
+      unusedReasons,
+    };
+  }
+
+  /**
+   * Validates equivalencies and identifies potential problems.
+   * Returns actionable issues that may indicate bugs or optimization opportunities.
+   *
+   * @example
+   * ```typescript
+   * const issues = sds.validateEquivalencies();
+   * if (issues.length > 0) {
+   *   console.log('Found issues:', issues);
+   * }
+   * ```
+   */
+  validateEquivalencies(): Array<{
+    type: 'broken_reference' | 'dead_end' | 'long_chain' | 'circular';
+    severity: 'error' | 'warning';
+    scope: string;
+    path: string;
+    details: string;
+  }> {
+    const issues: Array<{
+      type: 'broken_reference' | 'dead_end' | 'long_chain' | 'circular';
+      severity: 'error' | 'warning';
+      scope: string;
+      path: string;
+      details: string;
+    }> = [];
+
+    const allScopeNames = new Set([
+      ...Object.keys(this.scopeNodes),
+      ...this.externalFunctionCalls.map((fc) => fc.name),
+    ]);
+
+    // Check all scope nodes
+    for (const scopeName of Object.keys(this.scopeNodes)) {
+      const scopeNode = this.scopeNodes[scopeName];
+      const equivalencies = scopeNode.equivalencies ?? {};
+
+      for (const [path, eqs] of Object.entries(equivalencies)) {
+        for (const eq of eqs) {
+          // Check 1: Does the target scope exist?
+          if (!allScopeNames.has(eq.scopeNodeName)) {
+            issues.push({
+              type: 'broken_reference',
+              severity: 'error',
+              scope: scopeName,
+              path,
+              details: `Equivalency points to non-existent scope "${eq.scopeNodeName}"`,
+            });
+            continue;
+          }
+
+          // Check 2: Does the target path exist in target scope's schema or equivalencies?
+          const targetScope = this.getScopeOrFunctionCallInfo(eq.scopeNodeName);
+          if (targetScope) {
+            const hasInSchema = eq.schemaPath in (targetScope.schema ?? {});
+            const hasInEquivalencies =
+              eq.schemaPath in (targetScope.equivalencies ?? {});
+
+            // Only flag as dead end if it's a leaf path (no sub-properties exist)
+            if (!hasInSchema && !hasInEquivalencies) {
+              const hasSubPaths = Object.keys(targetScope.schema ?? {}).some(
+                (p) =>
+                  p.startsWith(eq.schemaPath + '.') ||
+                  p.startsWith(eq.schemaPath + '['),
+              );
+              if (!hasSubPaths) {
+                issues.push({
+                  type: 'dead_end',
+                  severity: 'warning',
+                  scope: scopeName,
+                  path,
+                  details: `Equivalency to "${eq.scopeNodeName}::${eq.schemaPath}" - path not in schema`,
+                });
+              }
+            }
+          }
+        }
+
+        // Check 3: Trace chain depth
+        const chain = this.traceEquivalencyChain(scopeName, path, 50);
+        if (chain.length >= 20) {
+          issues.push({
+            type: 'long_chain',
+            severity: 'warning',
+            scope: scopeName,
+            path,
+            details: `Equivalency chain depth is ${chain.length} (may impact performance)`,
+          });
+        }
+
+        // Check for potential cycles (chain that returns to starting point)
+        const visited = new Set<string>();
+        for (const step of chain) {
+          const key = `${step.scope}::${step.path}`;
+          if (visited.has(key)) {
+            issues.push({
+              type: 'circular',
+              severity: 'warning',
+              scope: scopeName,
+              path,
+              details: `Circular reference detected at ${key}`,
+            });
+            break;
+          }
+          visited.add(key);
+        }
+      }
+    }
+
+    return issues;
+  }
 }