@codeyam/codeyam-cli 0.1.0-staging.09652b8 → 0.1.0-staging.103bd05

package/packages/ai/src/lib/dataStructure/ScopeDataStructure.js

@@ -1,77 +1,268 @@
-/* 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 { joinParenthesesAndArrays, splitOutsideParenthesesAndArrays, } from "../splitOutsideParentheses.js";
 import fillInSchemaGapsAndUnknowns from "./helpers/fillInSchemaGapsAndUnknowns.js";
+import { clearCleanKnownObjectFunctionsCache } from "./helpers/cleanKnownObjectFunctions.js";
+import { clearCleanNonObjectFunctionsCache } from "./helpers/cleanNonObjectFunctions.js";
+/**
+ * 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.js";
-import cleanOutBoundary from "../cleanOutBoundary.js";
 import cleanPath from "./helpers/cleanPath.js";
+import { PathManager } from "./helpers/PathManager.js";
+import { uniqueId, uniqueScopeAndPaths, uniqueScopeVariables, } from "./helpers/uniqueIdUtils.js";
+import selectBestValue from "./helpers/selectBestValue.js";
+import { VisitedTracker } from "./helpers/VisitedTracker.js";
+import { DebugTracer } from "./helpers/DebugTracer.js";
+import { BatchSchemaProcessor } from "./helpers/BatchSchemaProcessor.js";
+import { ROOT_SCOPE_NAME, ScopeTreeManager, } from "./helpers/ScopeTreeManager.js";
 import cleanScopeNodeName from "./helpers/cleanScopeNodeName.js";
 import getFunctionCallRoot from "./helpers/getFunctionCallRoot.js";
 import cleanPathOfNonTransformingFunctions from "./helpers/cleanPathOfNonTransformingFunctions.js";
 import { arrayMethodsSet } from "./helpers/cleanNonObjectFunctions.js";
-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;
+    // Clear module-level caches to prevent unbounded memory growth across entities
+    const knownObjectCache = clearCleanKnownObjectFunctionsCache();
+    const nonObjectCache = clearCleanNonObjectFunctionsCache();
+    if (knownObjectCache.count > 0 || nonObjectCache.count > 0) {
+        const totalBytes = knownObjectCache.estimatedBytes + nonObjectCache.estimatedBytes;
+        console.log('CodeYam: Cleared analysis caches', {
+            knownObjectCache: `${knownObjectCache.count} entries, ${(knownObjectCache.estimatedBytes / 1024).toFixed(1)}KB`,
+            nonObjectCache: `${nonObjectCache.count} entries, ${(nonObjectCache.estimatedBytes / 1024).toFixed(1)}KB`,
+            totalKB: `${(totalBytes / 1024).toFixed(1)}KB`,
+        });
+    }
 }
+// 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',
+    // 'transformed non-object function equivalency - Explicit array deconstruction equivalency value',
+]);
 export class ScopeDataStructure {
+    // Getter for backward compatibility - returns the tree structure
+    get scopeTree() {
+        return this.scopeTreeManager.getTree();
+    }
     constructor(managers, scopeName = ROOT_SCOPE_NAME, scopeText, scopeAnalysis) {
         this.debugCount = 0;
         this.onlyEquivalencies = true;
         this.equivalencyManagers = [];
         this.scopeNodes = {};
-        this.scopeTree = { name: ROOT_SCOPE_NAME, children: [] };
+        this.scopeTreeManager = new ScopeTreeManager();
         this.externalFunctionCalls = [];
         this.environmentVariables = [];
         this.equivalencyDatabase = [];
+        /**
+         * Conditional usages collected during AST analysis.
+         * Maps local variable path to array of usages.
+         */
+        this.rawConditionalUsages = {};
+        /**
+         * Conditional effects collected during AST analysis.
+         * Tracks what setter calls happen inside conditionals (if, switch, ternary).
+         */
+        this.rawConditionalEffects = [];
+        /**
+         * Compound conditionals collected during AST analysis.
+         * Groups conditions that must all be true together (e.g., a && b && c).
+         */
+        this.rawCompoundConditionals = [];
+        /**
+         * Gating conditions for child component boundaries.
+         * Maps child component name to the conditions that must be true for it to render.
+         */
+        this.rawChildBoundaryGatingConditions = {};
+        /**
+         * JSX rendering usages collected during AST analysis.
+         * Tracks arrays rendered via .map() and strings interpolated in JSX.
+         */
+        this.rawJsxRenderingUsages = [];
         this.lastAddToSchemaId = 0;
         this.lastEquivalencyId = 0;
         this.lastEquivalencyDatabaseId = 0;
-        this.pathPartsCache = new Map();
-        this.pathJoinCache = new Map();
+        this.pathManager = new PathManager();
+        this.visitedTracker = new VisitedTracker();
         this.equivalencyDatabaseCache = new Map();
         // Inverted index: maps uniqueId -> EquivalencyDatabaseEntry for O(1) lookup
         this.intermediatesOrderIndex = new Map();
-        this.globalVisited = new Set();
-        // Separate visited set for addComplexSourcePathVariables - uses scope::path only (not value)
-        // This allows addComplexSourcePathVariables to run for each unique scope+path combo,
-        // while the main globalVisited uses scope+path+value for fine-grained deduplication
-        this.complexSourceVisited = new Set();
+        // Index for O(1) lookup of external function calls by name
+        // Invalidated by setting to null; rebuilt lazily on next access
+        this.externalFunctionCallsIndex = null;
+        // Tracks internal functions that have been filtered out during captureCompleteSchema
+        // Prevents re-adding them via subsequent equivalency propagation (e.g., from getReturnValue)
+        this.filteredInternalFunctions = new Set();
+        // Debug tracer for selective path/scope tracing
+        // Enable via: CODEYAM_DEBUG=true CODEYAM_DEBUG_PATHS="user.*,signature" npm test
+        this.tracer = 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
+        this.batchProcessor = 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
+        this.batchQueuedSet = null;
         this.equivalencyManagers.push(...managers);
-        this.scopeTree.name = scopeName;
+        this.scopeTreeManager.setRootName(scopeName);
         this.addScopeAnalysis(scopeName, scopeText, scopeAnalysis);
     }
     addScopeAnalysis(scopeNodeName, scopeText, scopeAnalysis, parentScopeName, isStatic) {
         try {
-            if (scopeNodeName !== this.scopeTree.name && !parentScopeName) {
-                parentScopeName = this.scopeTree.name;
+            if (scopeNodeName !== this.scopeTreeManager.getRootName() &&
+                !parentScopeName) {
+                parentScopeName = this.scopeTreeManager.getRootName();
             }
             let tree = [];
             if (parentScopeName) {
@@ -112,7 +303,7 @@ export class ScopeDataStructure {
         }
         catch (error) {
             console.log('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,
@@ -121,71 +312,148 @@ export class ScopeDataStructure {
             throw error;
         }
     }
+    /**
+     * 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([
-            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) => arrayMethodsList.some((method) => path.includes(`.${method}(`));
         for (const entry of this.equivalencyDatabase) {
-            entry.usages = entry.usages.filter((usage) => validExternalFacingScopeNames.has(usage.scopeNodeName.split('<')[0]) &&
-                (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]) &&
-                (candidate.schemaPath.startsWith('signature[') ||
-                    candidate.schemaPath.startsWith(candidate.scopeNodeName.split('<')[0])) &&
-                !Array.from(arrayMethodsSet).some((method) => candidate.schemaPath.includes(`.${method}(`)));
-        }
-        this.propagateSourceAndUsageEquivalencies(this.scopeNodes[this.scopeTree.name]);
+            entry.usages = entry.usages.filter((usage) => {
+                const baseName = this.pathManager.stripGenerics(usage.scopeNodeName);
+                return (validExternalFacingScopeNames.has(baseName) &&
+                    (usage.schemaPath.startsWith('returnValue') ||
+                        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(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.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, scopeNode, equivalencyValueChain = [], traceId, }) {
         addToSchemaCallCount++;
-        // DEBUG: Detect infinite loops
+        // 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,
@@ -199,14 +467,20 @@ export class ScopeDataStructure {
         if (equivalencyValueChain.length > maxEquivalencyChainDepth) {
             maxEquivalencyChainDepth = equivalencyValueChain.length;
         }
-        if (!scopeNode)
+        if (!scopeNode) {
             return;
+        }
         if (!this.isValidPath(path)) {
             if (traceId) {
                 console.info('Debug propagation: not a valid path', { path, traceId });
             }
             return;
         }
+        // PERF: Early exit for paths with repeated function-call signature patterns
+        if (this.hasExcessivePatternRepetition(path)) {
+            return;
+        }
+        // Update chain metadata for database tracking
         if (equivalencyValueChain.length > 0) {
             equivalencyValueChain[equivalencyValueChain.length - 1].addToSchemaId =
                 ++this.lastAddToSchemaId;
@@ -216,88 +490,35 @@ export class ScopeDataStructure {
                 value,
             };
         }
-        // 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);
-        // Call addComplexSourcePathVariables like the original code (before visited check)
+        // Process complex source paths (before visited check, per original design)
         this.addComplexSourcePathVariables(equivalenciesDatabaseEntry, scopeNode, path, equivalencyValueChain, 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);
             }
             return;
         }
-        this.globalVisited.add(uniqueIdentifier);
+        // Continue complex source processing after visited check
         this.captureComplexSourcePaths(equivalenciesDatabaseEntry, scopeNode, path, equivalencyValueChain, 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);
         let propagated = false;
@@ -385,45 +606,42 @@ 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 ||
                 scopeNode.instantiatedVariables.includes(pathParts[0]) ||
                 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,
+            console.info('Debug: addToSchema complete', {
+                scope: 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));
+            });
         }
     }
     removeFromSchema(path, schema = {}, scopeName) {
@@ -431,7 +649,6 @@ export class ScopeDataStructure {
     }
     addEquivalency(path, equivalentPath, equivalentScopeName, scopeNode, equivalencyReason, equivalencyValueChain, traceId) {
         var _a;
-        // DEBUG: Detect infinite loops
         addEquivalencyCallCount++;
         if (addEquivalencyCallCount > 50000) {
             console.error('INFINITE LOOP DETECTED in addEquivalency', {
@@ -444,61 +661,87 @@ export class ScopeDataStructure {
             });
             throw new Error(`Infinite loop detected: addEquivalency called ${addEquivalencyCallCount} times`);
         }
-        // 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',
-            'propagated sub-property equivalency',
-            'propagated function call return sub-property 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)) {
+        // 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;
+        }
+        // Case 3: Circular reference through scope-suffixed names (____cyScope pattern)
+        // When a named arrow function is defined inside a scope (e.g., useEffect callback):
+        //   const identifyUser = async () => { ... };
+        //   identifyUser();
+        // This creates a variable "identifyUser" and a scope "identifyUser____cyScope9F".
+        // Mutual equivalencies between these cause infinite loops in Phase 2 because
+        // processing one triggers addToSchema → followEquivalencies → addEquivalency
+        // on the reverse, which repeats indefinitely.
+        // Only block when the REVERSE direction already exists (creating a cycle).
+        // The initial one-directional equivalency is necessary for scope resolution.
+        if (path &&
+            equivalentPath &&
+            (equivalentPath.startsWith(path + '____') ||
+                path.startsWith(equivalentPath + '____'))) {
+            // Check if the reverse equivalency already exists
+            const reverseEquivalencies = scopeNode.equivalencies[equivalentPath] || [];
+            const reverseExists = reverseEquivalencies.some((v) => v.schemaPath === path);
+            if (reverseExists) {
+                return;
             }
         }
         if (!equivalentScopeName) {
-            console.warn('Debug Propagation: missing equivalent scope 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');
         }
         (_a = scopeNode.equivalencies)[path] || (_a[path] = []);
@@ -618,23 +861,60 @@ export class ScopeDataStructure {
             if (!functionCallInfo.equivalencies) {
                 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 = {
                     ...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 = !callingScopeNode.instantiatedVariables?.includes(functionCallInfoNameParts[0]) &&
                     !callingScopeNode.parentInstantiatedVariables?.includes(functionCallInfoNameParts[0]);
                 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();
+                    }
                 }
             }
         }
@@ -656,7 +936,7 @@ export class ScopeDataStructure {
         //   );
         // }
         const getRootOrExternalFunctionCallInfo = (name) => {
-            return name === this.scopeTree.name
+            return name === this.scopeTreeManager.getRootName()
                 ? this.getScopeNode()
                 : this.getExternalFunctionCallInfo(name);
         };
@@ -674,82 +954,70 @@ export class ScopeDataStructure {
                     schemaPath === safePath ||
                     safePath.startsWith(schemaPath));
             });
+            // 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();
+            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);
                 if (!pathParts.every((p, i) => schemaPathParts[i] === p)) {
                     continue;
                 }
                 const remainingSchemaPathParts = schemaPathParts.slice(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;
+                // 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;
                     }
-                    missingEquivalentPath = false;
                     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);
+                    // PERF: Skip paths with repeated function-call signature patterns
+                    // to prevent recursive type expansion (e.g., string.localeCompare returns string)
+                    if (this.hasExcessivePatternRepetition(schemaPath) ||
+                        this.hasExcessivePatternRepetition(equivalentSchemaPath)) {
+                        continue;
                     }
                     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,
-                    //   });
-                    // }
+                    // PERF: Skip paths with repeated function-call signature patterns
+                    if (this.hasExcessivePatternRepetition(newEquivalentPath)) {
+                        continue;
+                    }
                     equivalentScopeNode.schema[newEquivalentPath] =
                         scopeNode.schema[schemaPath];
                 }
@@ -772,101 +1040,137 @@ export class ScopeDataStructure {
         }
     }
     splitPath(path) {
-        if (this.pathPartsCache.has(path)) {
-            return structuredClone(this.pathPartsCache.get(path));
-        }
-        const pathParts = splitOutsideParenthesesAndArrays(path);
-        this.pathPartsCache.set(path, structuredClone(pathParts));
-        return pathParts;
+        return this.pathManager.splitPath(path);
     }
     joinPathParts(pathParts) {
-        const cacheKey = pathParts.join('|');
-        if (this.pathJoinCache.has(cacheKey)) {
-            return this.pathJoinCache.get(cacheKey);
+        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) {
+        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 //
-    uniqueId({ scopeNodeName, schemaPath, value, }) {
-        const parts = [scopeNodeName, schemaPath, value].filter(Boolean);
-        return parts.join('::');
+    uniqueId(params) {
+        return uniqueId(params);
     }
     uniqueScopeVariables(scopeVariables) {
-        return this.uniqueScopeAndPaths(scopeVariables);
+        return uniqueScopeVariables(scopeVariables);
     }
     uniqueScopeAndPaths(scopeVariables) {
-        if (!scopeVariables || scopeVariables.length === 0)
-            return [];
-        // Optimize from O(n²) to O(n) using Set for deduplication
-        const seen = new Set();
-        return scopeVariables.filter((varItem) => {
-            const key = `${varItem.scopeNodeName}::${varItem.schemaPath}`;
-            if (seen.has(key)) {
-                return false;
-            }
-            seen.add(key);
-            return true;
-        });
+        return uniqueScopeAndPaths(scopeVariables);
     }
     isValidPath(path) {
-        if (typeof path !== 'string') {
-            return false;
-        }
-        if (!path) {
-            return false;
-        }
-        if (path === 'true' || path === 'false') {
-            return false;
+        return this.pathManager.isValidPath(path);
+    }
+    /**
+     * 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
+     */
+    hasExcessivePatternRepetition(path, maxRepetitions = 2) {
+        // Check known recursive patterns
+        for (const pattern of RECURSIVE_PATH_PATTERNS) {
+            const matches = path.match(pattern);
+            if (matches && matches.length > maxRepetitions) {
+                return true;
+            }
         }
-        if (!isNaN(Number(path))) {
-            return false;
+        // Check for repeated function calls that indicate recursive type expansion.
+        // E.g., localeCompare(b[])...localeCompare(b[]) means string.localeCompare
+        // returns a type that again has localeCompare, causing infinite expansion.
+        // We extract all function call patterns like "funcName(args)" and check if
+        // the same normalized call appears more than once.
+        const funcCallPattern = /(?:^|\.)[^.([]+\([^)]*\)/g;
+        const funcCallMatches = path.match(funcCallPattern);
+        if (funcCallMatches && funcCallMatches.length > 1) {
+            const seen = new Set();
+            for (const match of funcCallMatches) {
+                // Strip leading dot and normalize array indices
+                const normalized = match.replace(/^\./, '').replace(/\[\d+\]/g, '[]');
+                if (seen.has(normalized))
+                    return true;
+                seen.add(normalized);
+            }
         }
-        if (path.match(/^['"]/)) {
+        // 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;
         }
-        return this.splitPath(path).every((part) => {
-            if (cleanOutBoundary(cleanOutBoundary(cleanOutBoundary(part, '<', '>'), '[', ']')).match(/\s/)) {
-                return false;
+        // Check for repeated sequences of 2-3 consecutive parts
+        for (let segmentLength = 2; segmentLength <= 3; segmentLength++) {
+            const seen = new Map();
+            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);
+                if (count > maxRepetitions) {
+                    return true;
+                }
             }
-            return true;
-        });
+        }
+        return false;
     }
     addToTree(pathParts) {
-        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: [],
-                };
-                scopeTreeNode.children.push(childScopeTreeNode);
-                scopeTreeNode = childScopeTreeNode;
-            }
-        }
+        this.scopeTreeManager.addPath(pathParts);
     }
     setInstantiatedVariables(scopeNode) {
         let instantiatedVariables = scopeNode.analysis?.instantiatedVariables ?? [];
-        for (const [path, equivalentPath] of Object.entries(scopeNode.analysis.isolatedEquivalentVariables ?? {})) {
-            if (typeof equivalentPath !== 'string') {
-                continue;
-            }
-            if (equivalentPath.startsWith('signature[')) {
-                const equivalentPathParts = this.splitPath(equivalentPath);
-                instantiatedVariables.push(equivalentPathParts[0]);
-                instantiatedVariables.push(path);
+        for (const [path, rawEquivalentPath] of Object.entries(scopeNode.analysis.isolatedEquivalentVariables ?? {})) {
+            // Normalize to array for consistent handling (supports both string and string[])
+            const equivalentPaths = Array.isArray(rawEquivalentPath)
+                ? rawEquivalentPath
+                : rawEquivalentPath
+                    ? [rawEquivalentPath]
+                    : [];
+            for (const equivalentPath of equivalentPaths) {
+                if (typeof equivalentPath !== 'string') {
+                    continue;
+                }
+                if (equivalentPath.startsWith('signature[')) {
+                    const equivalentPathParts = this.splitPath(equivalentPath);
+                    instantiatedVariables.push(equivalentPathParts[0]);
+                    instantiatedVariables.push(path);
+                }
             }
             const duplicateInstantiated = instantiatedVariables.find((v) => path.split('::cyDuplicateKey')[0] === v.split('::cyDuplicateKey')[0]);
             if (duplicateInstantiated) {
                 instantiatedVariables.push(path);
             }
         }
-        instantiatedVariables = instantiatedVariables.filter((varName, index, self) => self.indexOf(varName) === index);
+        const instantiatedSeen = new Set();
+        instantiatedVariables = instantiatedVariables.filter((varName) => {
+            if (instantiatedSeen.has(varName)) {
+                return false;
+            }
+            instantiatedSeen.add(varName);
+            return true;
+        });
         scopeNode.instantiatedVariables = instantiatedVariables;
         if (!scopeNode.tree || scopeNode.tree.length === 0) {
             return;
@@ -878,81 +1182,168 @@ export class ScopeDataStructure {
         const parentInstantiatedVariables = [
             ...(parentScopeNode.parentInstantiatedVariables ?? []),
             ...parentScopeNode.instantiatedVariables.filter((v) => !v.startsWith('signature[') && !v.startsWith('returnValue')),
-        ].filter((varName, index, self) => !instantiatedVariables.includes(varName) &&
-            self.indexOf(varName) === index);
-        scopeNode.parentInstantiatedVariables = parentInstantiatedVariables;
+        ].filter((varName) => !instantiatedSeen.has(varName));
+        const parentInstantiatedSeen = new Set();
+        const dedupedParentInstantiatedVariables = parentInstantiatedVariables.filter((varName) => {
+            if (parentInstantiatedSeen.has(varName)) {
+                return false;
+            }
+            parentInstantiatedSeen.add(varName);
+            return true;
+        });
+        scopeNode.parentInstantiatedVariables = dedupedParentInstantiatedVariables;
     }
     trackFunctionCalls(scopeNode) {
         this.captureFunctionCalls(scopeNode);
         this.checkExternalFunctionCalls();
     }
     determineEquivalenciesAndBuildSchema(scopeNode) {
+        if (!scopeNode.analysis) {
+            return;
+        }
         const { isolatedStructure, isolatedEquivalentVariables } = scopeNode.analysis;
+        // Flatten isolatedEquivalentVariables values for allPaths (handles both string and string[])
+        const flattenedEquivValues = Object.values(isolatedEquivalentVariables || {}).flatMap((v) => (Array.isArray(v) ? v : [v]));
         const allPaths = Array.from(new Set([
             ...Object.keys(isolatedStructure || {}),
             ...Object.keys(isolatedEquivalentVariables || {}),
-            ...Object.values(isolatedEquivalentVariables || {}),
+            ...flattenedEquivValues,
         ]));
         for (let path in isolatedEquivalentVariables) {
-            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);
-                this.addEquivalency(path, equivalentValue, scopeNode.name, scopeNode, 'original equivalency');
-                // 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.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');
-                                }
+            const rawEquivalentValue = isolatedEquivalentVariables?.[path];
+            // Normalize to array for consistent handling
+            const equivalentValues = Array.isArray(rawEquivalentValue)
+                ? rawEquivalentValue
+                : [rawEquivalentValue];
+            for (let equivalentValue of equivalentValues) {
+                if (equivalentValue && this.isValidPath(equivalentValue)) {
+                    // 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, equivalentValue, scopeNode.name, 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;
                             }
-                            // 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);
+                        }
+                    }
+                    // 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, rawSubValue] of Object.entries(checkScope.analysis.isolatedEquivalentVariables)) {
+                                // Normalize to array for consistent handling
+                                const subValues = Array.isArray(rawSubValue)
+                                    ? rawSubValue
+                                    : rawSubValue
+                                        ? [rawSubValue]
+                                        : [];
+                                // 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);
+                                    for (const subValue of subValues) {
+                                        if (typeof subValue !== 'string')
+                                            continue;
+                                        const newEquivalentValue = cleanPath(subValue.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
+                                for (const subValue of subValues) {
+                                    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);
+                    // 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,
@@ -965,19 +1356,95 @@ 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.
+     */
+    processBatchQueue() {
+        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);
+            if (!scopeNode)
+                continue;
+            this.addToSchema({
+                path: item.path,
+                value: item.value,
+                scopeNode,
+                equivalencyValueChain: item.equivalencyValueChain,
+                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.
+     */
+    trackReceivingVariable(receivingVariable, equivalentValue) {
+        // 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.
      *
@@ -1008,8 +1475,15 @@ export class ScopeDataStructure {
                 const checkScope = this.scopeNodes[scopeName];
                 if (!checkScope?.analysis?.isolatedEquivalentVariables)
                     continue;
-                const functionRef = checkScope.analysis.isolatedEquivalentVariables[functionName];
-                if (typeof functionRef === 'string' && functionRef.endsWith('F')) {
+                const rawFunctionRef = checkScope.analysis.isolatedEquivalentVariables[functionName];
+                // Normalize to array and find first string ending with 'F'
+                const functionRefs = Array.isArray(rawFunctionRef)
+                    ? rawFunctionRef
+                    : rawFunctionRef
+                        ? [rawFunctionRef]
+                        : [];
+                const functionRef = functionRefs.find((r) => typeof r === 'string' && r.endsWith('F'));
+                if (typeof functionRef === 'string') {
                     callbackScopeName = functionRef.slice(0, -1);
                     break;
                 }
@@ -1032,22 +1506,32 @@ export class ScopeDataStructure {
         if (!callbackScope.analysis?.isolatedEquivalentVariables)
             return;
         const isolatedVars = callbackScope.analysis.isolatedEquivalentVariables;
+        // Get the first returnValue equivalency (normalize array to single value for these checks)
+        const rawReturnValue = isolatedVars.returnValue;
+        const firstReturnValue = Array.isArray(rawReturnValue)
+            ? rawReturnValue[0]
+            : rawReturnValue;
         // 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
+        const returnValueAlias = typeof firstReturnValue === 'string' && !firstReturnValue.includes('.')
+            ? firstReturnValue
             : 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;
-        if (typeof isolatedVars.returnValue === 'string') {
-            const reduceMatch = isolatedVars.returnValue.match(/^Object\.keys\((\w+)\)\.reduce\(.*\)\.functionCallReturnValue$/);
+        if (typeof firstReturnValue === 'string') {
+            const reduceMatch = firstReturnValue.match(/^Object\.keys\((\w+)\)\.reduce\(.*\)\.functionCallReturnValue$/);
             if (reduceMatch) {
                 reduceSourceVar = reduceMatch[1];
             }
         }
-        for (const [subPath, subValue] of Object.entries(isolatedVars)) {
+        for (const [subPath, rawSubValue] of Object.entries(isolatedVars)) {
+            // Normalize to array for consistent handling
+            const subValues = Array.isArray(rawSubValue)
+                ? rawSubValue
+                : rawSubValue
+                    ? [rawSubValue]
+                    : [];
             // Check for direct returnValue.* sub-properties
             const isReturnValueSub = subPath.startsWith('returnValue.') ||
                 subPath.startsWith('returnValue[');
@@ -1059,33 +1543,36 @@ export class ScopeDataStructure {
             const isReduceSourceSub = reduceSourceVar &&
                 (subPath.startsWith(reduceSourceVar + '.') ||
                     subPath.startsWith(reduceSourceVar + '['));
-            if (typeof subValue !== 'string' ||
-                (!isReturnValueSub && !isAliasSub && !isReduceSourceSub))
+            if (!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);
+            for (const subValue of subValues) {
+                if (typeof subValue !== 'string')
+                    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);
+            }
         }
     }
     /**
@@ -1117,7 +1604,14 @@ export class ScopeDataStructure {
             const parentScope = this.scopeNodes[parentScopeName];
             if (!parentScope?.analysis?.isolatedEquivalentVariables)
                 continue;
-            const rootEquiv = parentScope.analysis.isolatedEquivalentVariables[rootVar];
+            const rawRootEquiv = parentScope.analysis.isolatedEquivalentVariables[rootVar];
+            // Normalize to array and use first string value
+            const rootEquivs = Array.isArray(rawRootEquiv)
+                ? rawRootEquiv
+                : rawRootEquiv
+                    ? [rawRootEquiv]
+                    : [];
+            const rootEquiv = rootEquivs.find((r) => typeof r === 'string');
             if (typeof rootEquiv === 'string') {
                 return {
                     resolvedPath: cleanPath(rootEquiv + restOfPath, allPaths),
@@ -1155,11 +1649,11 @@ export class ScopeDataStructure {
         }
     }
     checkForArrayItemPath(pathParts, scopeNode, equivalencyValueChain) {
-        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({
@@ -1176,27 +1670,77 @@ 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
+     */
     followEquivalencies(scopeNode, path, pathParts, subPath, subPathParts, value, equivalencyValueChain, traceId, 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('Debug Propagation: equivalence', JSON.stringify({
                 traceId,
@@ -1212,10 +1756,17 @@ export class ScopeDataStructure {
             }, null, 2));
         }
         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];
-            if (equivalentValue.id !== -1 &&
-                equivalencyValueChain.some((ev) => ev.id === equivalentValue.id)) {
+            // O(1) cycle check using Set instead of O(n) .some()
+            if (chainIdSet &&
+                equivalentValue.id !== -1 &&
+                chainIdSet.has(equivalentValue.id)) {
                 if (traceId) {
                     console.info('Debug Propagation: skipping circular equivalence', JSON.stringify({
                         traceId,
@@ -1243,16 +1794,32 @@ export class ScopeDataStructure {
             if (lastRelevantSubPathPart.endsWith(')') &&
                 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);
             const remainingPath = this.joinPathParts(remainingPathParts);
             if (relevantSubPathParts.every((part, i) => part === schemaPathParts[i]) &&
                 equivalentValue.scopeNodeName === scopeNode.name) {
+                // DEBUG
                 continue;
             }
             const newEquivalentPath = this.joinPathParts([schemaPath, remainingPath]);
+            // 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', {
@@ -1287,23 +1854,27 @@ export class ScopeDataStructure {
                         // equivalencies:  scopeNode.equivalencies,
                     }, null, 2));
                 }
-                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,
                 //   subPath,
@@ -1313,13 +1884,48 @@ export class ScopeDataStructure {
                 //   equivalentValue.equivalencyReason,
                 // )
                 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, 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,
+                    });
+                }
             }
         }
         return propagated;
@@ -1341,13 +1947,13 @@ export class ScopeDataStructure {
                         return;
                     }
                     const usageScopeNode = this.getScopeOrFunctionCallInfo(usageEquivalency.scopeNodeName);
+                    if (!usageScopeNode)
+                        continue;
                     // Guard against infinite recursion by tracking which paths we've already
                     // added from addComplexSourcePathVariables
-                    const complexPathKey = `${usageScopeNode.name}::${newUsageEquivalentPath}`;
-                    if (this.complexSourceVisited.has(complexPathKey)) {
+                    if (this.visitedTracker.checkAndMarkComplexSourceVisited(usageScopeNode.name, newUsageEquivalentPath)) {
                         continue;
                     }
-                    this.complexSourceVisited.add(complexPathKey);
                     this.addToSchema({
                         path: newUsageEquivalentPath,
                         value: 'unknown',
@@ -1391,6 +1997,8 @@ export class ScopeDataStructure {
                         continue;
                     }
                     const usageScopeNode = this.getScopeOrFunctionCallInfo(usageEquivalency.scopeNodeName);
+                    if (!usageScopeNode)
+                        continue;
                     // This is put in place to avoid propagating array functions like 'filter' through complex equivalencies
                     // but may cause problems if the funtion call is not on a known object (e.g. string or array)
                     if (newUsageEquivalentPath.endsWith(')') ||
@@ -1487,9 +2095,70 @@ export class ScopeDataStructure {
             // Update inverted index
             this.intermediatesOrderIndex.set(pathId, databaseEntry);
             if (intermediateIndex === 0) {
-                const isValidSourceCandidate = pathInfo.schemaPath.startsWith('signature[') ||
+                let isValidSourceCandidate = pathInfo.schemaPath.startsWith('signature[') ||
                     pathInfo.schemaPath.includes('functionCallReturnValue');
-                if (isValidSourceCandidate) {
+                // Check if path STARTS with a spread pattern like [...var]
+                // This handles cases like [...files][][0] or [...files].sort(...).functionCallReturnValue[][0]
+                // where the spread source variable needs to be resolved to a signature path.
+                // We do this REGARDLESS of isValidSourceCandidate because even paths containing
+                // functionCallReturnValue may need spread resolution to trace back to the signature.
+                const spreadMatch = pathInfo.schemaPath.match(/^\[\.\.\.(\w+)\]/);
+                if (spreadMatch) {
+                    const spreadVar = spreadMatch[1];
+                    const spreadPattern = spreadMatch[0]; // The full [...var] match
+                    const scopeNode = this.scopeNodes[pathInfo.scopeNodeName];
+                    if (scopeNode?.equivalencies) {
+                        // Follow the equivalency chain to find a signature path
+                        // e.g., files (cyScope1) → files (root) → signature[0].files
+                        const resolveToSignature = (varName, currentScopeName, visited) => {
+                            const visitKey = `${currentScopeName}::${varName}`;
+                            if (visited.has(visitKey))
+                                return null;
+                            visited.add(visitKey);
+                            const currentScope = this.scopeNodes[currentScopeName];
+                            if (!currentScope?.equivalencies)
+                                return null;
+                            const varEquivs = currentScope.equivalencies[varName];
+                            if (!varEquivs)
+                                return null;
+                            // First check if any equivalency directly points to a signature path
+                            const signatureEquiv = varEquivs.find((eq) => eq.schemaPath.startsWith('signature['));
+                            if (signatureEquiv) {
+                                return signatureEquiv;
+                            }
+                            // Otherwise, follow the chain to other scopes
+                            for (const equiv of varEquivs) {
+                                // If the equivalency points to the same variable in a different scope,
+                                // follow the chain
+                                if (equiv.schemaPath === varName &&
+                                    equiv.scopeNodeName !== currentScopeName) {
+                                    const result = resolveToSignature(varName, equiv.scopeNodeName, visited);
+                                    if (result)
+                                        return result;
+                                }
+                            }
+                            return null;
+                        };
+                        const signatureEquiv = resolveToSignature(spreadVar, pathInfo.scopeNodeName, new Set());
+                        if (signatureEquiv) {
+                            // Replace ONLY the [...var] part with the resolved signature path
+                            // This preserves any suffix like .sort(...).functionCallReturnValue[][0]
+                            const resolvedPath = pathInfo.schemaPath.replace(spreadPattern, signatureEquiv.schemaPath);
+                            // Add the resolved path as a source candidate
+                            if (!databaseEntry.sourceCandidates.some((sc) => sc.schemaPath === resolvedPath &&
+                                sc.scopeNodeName === pathInfo.scopeNodeName)) {
+                                databaseEntry.sourceCandidates.push({
+                                    scopeNodeName: pathInfo.scopeNodeName,
+                                    schemaPath: resolvedPath,
+                                });
+                            }
+                            isValidSourceCandidate = true;
+                        }
+                    }
+                }
+                if (isValidSourceCandidate &&
+                    !databaseEntry.sourceCandidates.some((sc) => sc.schemaPath === pathInfo.schemaPath &&
+                        sc.scopeNodeName === pathInfo.scopeNodeName)) {
                     databaseEntry.sourceCandidates.push(pathInfo);
                 }
             }
@@ -1542,6 +2211,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;
                     if (localEquivalentPath.startsWith(externalFunctionCallInfo.callSignature)) {
@@ -1584,15 +2254,17 @@ 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,
                         callSignature,
@@ -1604,15 +2276,17 @@ export class ScopeDataStructure {
             for (const equivalentValues of scopeNode.equivalencies[key]) {
                 const equivalentValueParts = this.splitPath(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,
                             callSignature,
@@ -1630,6 +2304,13 @@ export class ScopeDataStructure {
                 delete scopeNode.schema[key];
             }
         }
+        // Ensure parameter-to-signature equivalencies are fully propagated.
+        // When a parameter variable (e.g., `node`) is equivalenced to `signature[N]`,
+        // all sub-paths of that variable should also appear under `signature[N]`.
+        // This handles cases where the sub-path was added to the schema via a propagation
+        // chain that already included the variable↔signature equivalency, causing the
+        // cycle detection to prevent the reverse mapping.
+        this.propagateParameterToSignaturePaths(scopeNode);
         fillInSchemaGapsAndUnknowns(scopeNode, fillInUnknowns);
         if (final) {
             for (const manager of this.equivalencyManagers) {
@@ -1641,8 +2322,87 @@ export class ScopeDataStructure {
             ensureSchemaConsistency(scopeNode.schema);
         }
     }
-    filterAndConvertSchema({ filterPath, newPath, schema, }) {
-        const filterPathParts = this.splitPath(filterPath);
+    /**
+     * For each equivalency where a simple variable maps to signature[N],
+     * ensure all sub-paths of that variable are reflected under signature[N].
+     */
+    propagateParameterToSignaturePaths(scopeNode) {
+        // Helper: check if a type is a concrete scalar that cannot have sub-properties.
+        const SCALAR_TYPES = new Set([
+            'string',
+            'number',
+            'boolean',
+            'bigint',
+            'symbol',
+            'void',
+            'never',
+        ]);
+        const isDefinitelyScalar = (type) => {
+            const parts = type.split('|').map((s) => s.trim());
+            const base = parts.filter((s) => s !== 'undefined' && s !== 'null');
+            return base.length > 0 && base.every((b) => SCALAR_TYPES.has(b));
+        };
+        // Find variable → signature[N] equivalencies
+        for (const [varName, equivalencies] of Object.entries(scopeNode.equivalencies)) {
+            // Only process simple variable names (no dots, brackets, or parens)
+            if (varName.includes('.') ||
+                varName.includes('[') ||
+                varName.includes('(')) {
+                continue;
+            }
+            for (const equiv of equivalencies) {
+                if (equiv.scopeNodeName === scopeNode.name &&
+                    equiv.schemaPath.startsWith('signature[')) {
+                    const signaturePath = equiv.schemaPath;
+                    const varPrefix = varName + '.';
+                    const varBracketPrefix = varName + '[';
+                    // Find all schema keys starting with the variable
+                    for (const key in scopeNode.schema) {
+                        if (key.startsWith(varPrefix) || key.startsWith(varBracketPrefix)) {
+                            const suffix = key.slice(varName.length);
+                            const sigKey = signaturePath + suffix;
+                            // Only add if the signature path doesn't already exist
+                            if (!scopeNode.schema[sigKey]) {
+                                // Check if this path represents variable conflation:
+                                // When a standalone variable (e.g., showWorkoutForm from useState)
+                                // appears as a sub-property of a scalar-typed ancestor (e.g.,
+                                // activity_type = "string"), it's from scope conflation, not real
+                                // property access. Block these while allowing legitimate built-in
+                                // accesses like string.length or string.slice.
+                                let isConflatedPath = false;
+                                let checkPos = signaturePath.length;
+                                while (true) {
+                                    checkPos = sigKey.indexOf('.', checkPos + 1);
+                                    if (checkPos === -1)
+                                        break;
+                                    const ancestorPath = sigKey.substring(0, checkPos);
+                                    const ancestorType = scopeNode.schema[ancestorPath];
+                                    if (ancestorType && isDefinitelyScalar(ancestorType)) {
+                                        // Ancestor is scalar — check if the immediate sub-property
+                                        // is also a standalone variable (indicating conflation)
+                                        const afterDot = sigKey.substring(checkPos + 1);
+                                        const nextSep = afterDot.search(/[.\[]/);
+                                        const subPropName = nextSep === -1
+                                            ? afterDot
+                                            : afterDot.substring(0, nextSep);
+                                        if (scopeNode.schema[subPropName] !== undefined) {
+                                            isConflatedPath = true;
+                                            break;
+                                        }
+                                    }
+                                }
+                                if (!isConflatedPath) {
+                                    scopeNode.schema[sigKey] = scopeNode.schema[key];
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    filterAndConvertSchema({ filterPath, newPath, schema, }) {
+        const filterPathParts = this.splitPath(filterPath);
         return Object.keys(schema).reduce((acc, key) => {
             const keyParts = this.splitPath(key);
             if (!filterPathParts.every((part, index) => keyParts[index] === part)) {
@@ -1700,6 +2460,10 @@ export class ScopeDataStructure {
                             path,
                             ...this.splitPath(key).slice(equivalentValueSchemaPathParts.length),
                         ]);
+                        // PERF: Skip keys with repeated function-call signature patterns
+                        // to prevent recursive type expansion (e.g., string.localeCompare returns string)
+                        if (this.hasExcessivePatternRepetition(newKey))
+                            continue;
                         resolvedSchema[newKey] = value;
                     }
                 }
@@ -1721,6 +2485,9 @@ export class ScopeDataStructure {
                 if (!subSchema)
                     continue;
                 for (const resolvedKey in subSchema) {
+                    // PERF: Skip keys with repeated function-call signature patterns
+                    if (this.hasExcessivePatternRepetition(resolvedKey))
+                        continue;
                     if (!resolvedSchema[resolvedKey] ||
                         subSchema[resolvedKey] === 'unknown') {
                         resolvedSchema[resolvedKey] = subSchema[resolvedKey];
@@ -1757,7 +2524,7 @@ export class ScopeDataStructure {
         return this.getExternalFunctionCallInfo(scopeName);
     }
     getScopeNode(scopeName) {
-        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) {
@@ -1766,20 +2533,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.
+     */
+    getExternalFunctionCallsIndex() {
+        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.
+     */
+    invalidateExternalFunctionCallsIndex() {
+        this.externalFunctionCallsIndex = null;
+    }
     getExternalFunctionCallInfo(functionName) {
-        return this.externalFunctionCalls.find((efc) => efc.name === getFunctionCallRoot(functionName) ||
-            efc.name.split('<')[0] === getFunctionCallRoot(functionName));
+        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 === searchKey ||
+            this.pathManager.stripGenerics(efc.name) === searchKey);
     }
     getScopeAnalysis(scopeName) {
-        return this.scopeNodes[scopeName ?? this.scopeTree.name].analysis;
+        return this.scopeNodes[scopeName ?? this.scopeTreeManager.getRootName()]
+            .analysis;
     }
     getAnalysisTree() {
         return this.scopeTree;
     }
     getSchema({ scopeName, fillInUnknowns, }) {
-        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;
             return Object.keys(externalFunctionCallSchema).reduce((acc, key) => {
@@ -1789,9 +2590,56 @@ export class ScopeDataStructure {
                 return acc;
             }, {});
         }
+        // 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.
+     */
+    filterDuplicateKeys(schema) {
+        return Object.entries(schema).reduce((acc, [key, value]) => {
+            if (!key.includes('::cyDuplicateKey')) {
+                acc[key] = value;
+            }
+            return acc;
+        }, {});
     }
     getEquivalencies(scopeName) {
         const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
@@ -1802,7 +2650,9 @@ export class ScopeDataStructure {
         if (this.equivalencyDatabaseCache.has(cacheKey)) {
             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;
     }
@@ -1811,18 +2661,204 @@ export class ScopeDataStructure {
         if (!scopeNode) {
             return {};
         }
-        const entries = this.equivalencyDatabase.filter((entry) => entry.usages.some((usage) => usage.scopeNodeName === scopeNode.name));
-        return entries.reduce((acc, entry) => {
+        // Collect all descendant scope names (including the scope itself)
+        // This ensures we include external calls from nested scopes like cyScope2
+        const getAllDescendantScopeNames = (node) => {
+            const names = new Set([node.name]);
+            for (const child of node.children) {
+                for (const name of getAllDescendantScopeNames(child)) {
+                    names.add(name);
+                }
+            }
+            return names;
+        };
+        const treeNode = this.scopeTreeManager.findNode(scopeNode.name);
+        const descendantScopeNames = treeNode
+            ? getAllDescendantScopeNames(treeNode)
+            : new Set([scopeNode.name]);
+        // Get all external function calls made from this scope or any descendant scope
+        // This allows us to include prop equivalencies from JSX components
+        // that were rendered in nested scopes (e.g., FileTableRow called from cyScope2)
+        const externalCallsFromScope = this.externalFunctionCalls.filter((efc) => descendantScopeNames.has(efc.callScope));
+        const externalCallNames = new Set(externalCallsFromScope.map((efc) => efc.name));
+        // Helper to check if a usage belongs to this scope (directly, via descendant, or via external call)
+        const usageMatchesScope = (usage) => descendantScopeNames.has(usage.scopeNodeName) ||
+            externalCallNames.has(usage.scopeNodeName);
+        const entries = this.equivalencyDatabase.filter((entry) => entry.usages.some(usageMatchesScope));
+        // Helper to resolve a source candidate through equivalency chains to find signature paths
+        const resolveToSignature = (source, visited) => {
+            const visitKey = `${source.scopeNodeName}::${source.schemaPath}`;
+            if (visited.has(visitKey))
+                return [];
+            visited.add(visitKey);
+            // If already a signature path, return as-is
+            if (source.schemaPath.startsWith('signature[')) {
+                return [source];
+            }
+            const currentScope = this.scopeNodes[source.scopeNodeName];
+            if (!currentScope?.equivalencies)
+                return [source];
+            // Check for direct equivalencies FIRST (full path match)
+            // This ensures paths like "useMemo(...).functionCallReturnValue" follow to "cyScope1::returnValue"
+            // before prefix matching tries "useMemo(...)" which goes to the useMemo scope
+            const directEquivs = currentScope.equivalencies[source.schemaPath];
+            if (directEquivs?.length > 0) {
+                const results = [];
+                for (const equiv of directEquivs) {
+                    const resolved = resolveToSignature({
+                        scopeNodeName: equiv.scopeNodeName,
+                        schemaPath: equiv.schemaPath,
+                    }, visited);
+                    results.push(...resolved);
+                }
+                if (results.length > 0)
+                    return results;
+            }
+            // Handle spread patterns like [...items].sort().functionCallReturnValue
+            // Extract the spread variable and resolve it through the equivalency chain
+            const spreadMatch = source.schemaPath.match(/^\[\.\.\.(\w+)\]/);
+            if (spreadMatch) {
+                const spreadVar = spreadMatch[1];
+                const spreadPattern = spreadMatch[0];
+                const varEquivs = currentScope.equivalencies[spreadVar];
+                if (varEquivs?.length > 0) {
+                    const results = [];
+                    for (const equiv of varEquivs) {
+                        // Follow the variable equivalency and then resolve from there
+                        const resolvedVar = resolveToSignature({
+                            scopeNodeName: equiv.scopeNodeName,
+                            schemaPath: equiv.schemaPath,
+                        }, visited);
+                        // For each resolved variable path, create the full path with array element suffix
+                        for (const rv of resolvedVar) {
+                            if (rv.schemaPath.startsWith('signature[')) {
+                                // Get the suffix after the spread pattern
+                                let suffix = source.schemaPath.slice(spreadPattern.length);
+                                // Clean the suffix: strip array method chains like .sort(...).functionCallReturnValue[]
+                                // These don't change the data identity, just transform it.
+                                // Keep only the final element access parts like [0], [1], etc.
+                                // Pattern: strip everything from a method call up through functionCallReturnValue[]
+                                suffix = suffix.replace(/\.\w+\([^)]*\)\.functionCallReturnValue\[\]/g, '');
+                                // Also handle simpler case without nested parens
+                                suffix = suffix.replace(/\.sort\(\w*\(\)\)\.functionCallReturnValue\[\]/g, '');
+                                // Add [] to indicate array element access from the spread
+                                const resolvedPath = rv.schemaPath + '[]' + suffix;
+                                results.push({
+                                    scopeNodeName: rv.scopeNodeName,
+                                    schemaPath: resolvedPath,
+                                });
+                            }
+                        }
+                    }
+                    if (results.length > 0)
+                        return results;
+                }
+            }
+            // Try to find prefix equivalencies that can resolve this path
+            // For path like "cyScope3().signature[0][0]", check "cyScope3().signature[0]", etc.
+            const pathParts = this.splitPath(source.schemaPath);
+            for (let i = pathParts.length - 1; i > 0; i--) {
+                const prefix = this.joinPathParts(pathParts.slice(0, i));
+                const suffix = this.joinPathParts(pathParts.slice(i));
+                const prefixEquivs = currentScope.equivalencies[prefix];
+                if (prefixEquivs?.length > 0) {
+                    const results = [];
+                    for (const equiv of prefixEquivs) {
+                        const newPath = this.joinPathParts([equiv.schemaPath, suffix]);
+                        const resolved = resolveToSignature({ scopeNodeName: equiv.scopeNodeName, schemaPath: newPath }, visited);
+                        results.push(...resolved);
+                    }
+                    if (results.length > 0)
+                        return results;
+                }
+            }
+            return [source];
+        };
+        const acc = entries.reduce((result, entry) => {
             var _a;
             if (entry.sourceCandidates.length === 0)
-                return acc;
-            const usages = entry.usages.filter((u) => u.scopeNodeName === scopeNode.name);
+                return result;
+            const usages = entry.usages.filter(usageMatchesScope);
             for (const usage of usages) {
-                acc[_a = usage.schemaPath] || (acc[_a] = []);
-                acc[usage.schemaPath].push(...entry.sourceCandidates);
+                result[_a = usage.schemaPath] || (result[_a] = []);
+                // Resolve each source candidate through the equivalency chain
+                for (const source of entry.sourceCandidates) {
+                    const resolvedSources = resolveToSignature(source, new Set());
+                    result[usage.schemaPath].push(...resolvedSources);
+                }
             }
-            return acc;
+            return result;
         }, {});
+        // Post-processing: enrich useState-backed sources with co-located external
+        // function calls. When a useState value resolves to a setter variable that
+        // lives in the same scope as a fetch/API call, that fetch is a data source.
+        this.enrichUseStateSourcesWithCoLocatedCalls(acc);
+        return acc;
+    }
+    /**
+     * For each source that ends at a useState path, check if the setter was called
+     * from a scope that also contains external function calls (like fetch).
+     * If so, add those external calls as additional source candidates.
+     */
+    enrichUseStateSourcesWithCoLocatedCalls(acc) {
+        const rootScopeName = this.scopeTreeManager.getRootName();
+        const rootScope = this.scopeNodes[rootScopeName];
+        if (!rootScope)
+            return;
+        // Collect all descendants for each scope node
+        const getAllDescendants = (node) => {
+            const names = new Set([node.name]);
+            for (const child of node.children) {
+                for (const name of getAllDescendants(child)) {
+                    names.add(name);
+                }
+            }
+            return names;
+        };
+        for (const [usagePath, sources] of Object.entries(acc)) {
+            const additionalSources = [];
+            for (const source of sources) {
+                // Check if this source is a useState-related terminal path
+                // (e.g., useState(X).functionCallReturnValue[1] or useState(X).signature[0])
+                if (!source.schemaPath.match(/^useState\([^)]*\)\./))
+                    continue;
+                // Find the useState call from the source path
+                const useStateCallMatch = source.schemaPath.match(/^(useState\([^)]*\))\./);
+                if (!useStateCallMatch)
+                    continue;
+                const useStateCall = useStateCallMatch[1];
+                // Look in the root scope for the useState value equivalency
+                // which tells us where the setter was called from
+                const valuePath = `${useStateCall}.functionCallReturnValue[0]`;
+                const valueEquivs = rootScope.equivalencies[valuePath];
+                if (!valueEquivs)
+                    continue;
+                for (const equiv of valueEquivs) {
+                    // Find the scope where the setter was called
+                    const setterScopeName = equiv.scopeNodeName;
+                    const setterScopeTree = this.scopeTreeManager.findNode(setterScopeName);
+                    if (!setterScopeTree)
+                        continue;
+                    // Get all descendant scope names from the setter scope
+                    const relatedScopes = getAllDescendants(setterScopeTree);
+                    // Find external function calls in those scopes whose return values
+                    // are actually consumed (assigned to a variable). This excludes
+                    // fire-and-forget calls like analytics.track() or console.log().
+                    const coLocatedCalls = this.externalFunctionCalls.filter((efc) => relatedScopes.has(efc.callScope) &&
+                        efc.receivingVariableNames &&
+                        efc.receivingVariableNames.length > 0);
+                    for (const call of coLocatedCalls) {
+                        additionalSources.push({
+                            scopeNodeName: call.callScope,
+                            schemaPath: `${call.callSignature}.functionCallReturnValue`,
+                        });
+                    }
+                }
+            }
+            if (additionalSources.length > 0) {
+                acc[usagePath].push(...additionalSources);
+            }
+        }
     }
     getUsageEquivalencies(functionName) {
         const scopeNode = this.getScopeOrFunctionCallInfo(functionName);
@@ -1855,22 +2891,194 @@ export class ScopeDataStructure {
             return acc;
         }, {});
         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';
                 }
             }
         }
-        const tempScopeNode = this.createTempScopeNode(functionName ?? this.scopeTree.name, signatureInSchema, equivalencies);
+        const tempScopeNode = this.createTempScopeNode(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 = {};
+        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;
+                }
+            }
+        }
+        // Enrich schema with deeply nested paths from internal function call scopes.
+        // When a function call like traverse(tree) exists, and traverse's scope has
+        // signature[0].children[path][entityName] (from propagateParameterToSignaturePaths),
+        // we need to map those paths back to the argument variable (tree) in this scope.
+        // This handles cases where cycle detection prevented the equivalency chain from
+        // propagating deep paths during Phase 2 batch queue processing.
+        for (const equivalenceKey in equivalencies ?? {}) {
+            // Look for keys matching function call pattern: funcName(...).signature[N]
+            const funcCallMatch = equivalenceKey.match(/^([^(]+)\(.*?\)\.(signature\[\d+\])$/);
+            if (!funcCallMatch)
+                continue;
+            const calledFunctionName = funcCallMatch[1];
+            const signatureParam = funcCallMatch[2]; // e.g., "signature[0]"
+            for (const equivalenceValue of equivalencies[equivalenceKey]) {
+                if (equivalenceValue.scopeNodeName !== scopeName)
+                    continue;
+                const targetVariable = equivalenceValue.schemaPath;
+                // Get the called function's schema (includes propagated parameter paths)
+                const childSchema = this.getSchema({
+                    scopeName: calledFunctionName,
+                });
+                if (!childSchema)
+                    continue;
+                // Map child function's signature paths to parent variable paths
+                const sigPrefix = signatureParam + '.';
+                const sigBracketPrefix = signatureParam + '[';
+                for (const childKey in childSchema) {
+                    let suffix = null;
+                    if (childKey.startsWith(sigPrefix)) {
+                        suffix = childKey.slice(signatureParam.length);
+                    }
+                    else if (childKey.startsWith(sigBracketPrefix)) {
+                        suffix = childKey.slice(signatureParam.length);
+                    }
+                    if (suffix !== null) {
+                        const parentKey = targetVariable + suffix;
+                        if (!schema[parentKey]) {
+                            schema[parentKey] = childSchema[childKey];
+                        }
+                    }
+                }
+            }
+        }
+        // Helper: check if a type is a concrete scalar that cannot have sub-properties.
+        // e.g., "string", "number | undefined", "boolean | null" are scalar.
+        // "object", "array", "function", "unknown", "Workout", etc. are NOT scalar.
+        const SCALAR_TYPES = new Set([
+            'string',
+            'number',
+            'boolean',
+            'bigint',
+            'symbol',
+            'void',
+            'never',
+        ]);
+        const isDefinitelyScalarType = (type) => {
+            const parts = type.split('|').map((s) => s.trim());
+            const base = parts.filter((s) => s !== 'undefined' && s !== 'null');
+            return base.length > 0 && base.every((b) => SCALAR_TYPES.has(b));
+        };
+        // 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]) {
+                        // Check if this path represents variable conflation:
+                        // When a standalone variable (e.g., showWorkoutForm from useState)
+                        // appears as a sub-property of a scalar-typed ancestor (e.g.,
+                        // activity_type = "string"), it's from scope conflation, not real
+                        // property access. Block these while allowing legitimate built-in
+                        // accesses like string.length or string.slice.
+                        let isConflatedPath = false;
+                        let checkPos = signaturePath.length;
+                        while (true) {
+                            checkPos = signatureKey.indexOf('.', checkPos + 1);
+                            if (checkPos === -1)
+                                break;
+                            const ancestorPath = signatureKey.substring(0, checkPos);
+                            const ancestorType = tempScopeNode.schema[ancestorPath];
+                            if (ancestorType && isDefinitelyScalarType(ancestorType)) {
+                                // Ancestor is scalar — check if the immediate sub-property
+                                // is also a standalone variable (indicating conflation)
+                                const afterDot = signatureKey.substring(checkPos + 1);
+                                const nextSep = afterDot.search(/[.\[]/);
+                                const subPropName = nextSep === -1 ? afterDot : afterDot.substring(0, nextSep);
+                                if (schema[subPropName] !== undefined) {
+                                    isConflatedPath = true;
+                                    break;
+                                }
+                            }
+                        }
+                        if (!isConflatedPath) {
+                            tempScopeNode.schema[signatureKey] = schema[schemaKey];
+                        }
+                    }
+                }
+            }
+        }
+        // Post-process: filter out conflated signature paths.
+        // During phase 2 scope analysis, useState(false) conflation can create
+        // bad paths like signature[0].mockWorkouts[].activity_type.showWorkoutForm
+        // directly in scopeNode.schema. These flow through signatureInSchema into
+        // tempScopeNode.schema without any guard. Filter them out here by checking:
+        //   1. An ancestor in the path has a concrete scalar type (string, number, boolean, etc.)
+        //   2. The immediate sub-property of that scalar ancestor is also a standalone
+        //      variable in the schema (indicating conflation, not a real property access)
+        for (const key of Object.keys(tempScopeNode.schema)) {
+            if (!key.startsWith('signature['))
+                continue;
+            // Walk through the path looking for scalar-typed ancestors
+            let pos = 0;
+            while (true) {
+                pos = key.indexOf('.', pos + 1);
+                if (pos === -1)
+                    break;
+                const ancestorPath = key.substring(0, pos);
+                const ancestorType = tempScopeNode.schema[ancestorPath];
+                if (ancestorType && isDefinitelyScalarType(ancestorType)) {
+                    // Found a scalar ancestor — check if the sub-property name
+                    // is a standalone variable in the getSchema() result
+                    const afterDot = key.substring(pos + 1);
+                    const nextSep = afterDot.search(/[.\[]/);
+                    const subPropName = nextSep === -1 ? afterDot : afterDot.substring(0, nextSep);
+                    if (schema[subPropName] !== undefined) {
+                        delete tempScopeNode.schema[key];
+                        break;
+                    }
+                }
+            }
+        }
+        return this.filterDuplicateKeys(tempScopeNode.schema);
     }
     getReturnValue({ functionName, fillInUnknowns, }) {
-        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 = {};
         if (scopeNode) {
@@ -1880,19 +3088,15 @@ export class ScopeDataStructure {
             });
         }
         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));
                 const nameParts = this.splitPath(externalFunctionCall.name).map((p) => this.functionOrScopeName(p));
                 if (functionNameParts.every((part, index) => part === nameParts[index])) {
                     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);
                     }
                 }
             }
@@ -1906,14 +3110,27 @@ 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) => {
             acc[key] = schema[key];
             const keyParts = this.splitPath(key);
             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];
+                    }
                 }
             }
             return acc;
@@ -1921,12 +3138,68 @@ export class ScopeDataStructure {
         // Replace cyScope placeholders with actual callback text
         const resolvedSchema = this.replaceCyScopePlaceholders(returnValueSchema);
         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);
-        return tempScopeNode.schema;
+        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)
+     */
+    isBareCallSignature(key) {
+        // 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;
+            }
+        }
+        // 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.
      */
     replaceCyScopePlaceholders(schema) {
         const cyScopePattern = /cyScope(\d+)\(\)/g;
@@ -1938,10 +3211,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;
         }
@@ -1989,19 +3262,378 @@ export class ScopeDataStructure {
         return scopeText;
     }
     getEquivalentSignatureVariables() {
-        const scopeNode = this.scopeNodes[this.scopeTree.name];
+        const scopeNode = this.scopeNodes[this.scopeTreeManager.getRootName()];
         const equivalentSignatureVariables = {};
+        // Helper to add equivalencies - accumulates into array if multiple values for same key
+        // This is critical for OR expressions like `x = a || b` where x should map to both a and b
+        const addEquivalency = (key, value) => {
+            const existing = equivalentSignatureVariables[key];
+            if (existing === undefined) {
+                // First value - store as string
+                equivalentSignatureVariables[key] = value;
+            }
+            else if (typeof existing === 'string') {
+                if (existing !== value) {
+                    // Second different value - convert to array
+                    equivalentSignatureVariables[key] = [existing, value];
+                }
+                // Same value - no change needed
+            }
+            else {
+                // Already an array - add if not already present
+                if (!existing.includes(value)) {
+                    existing.push(value);
+                }
+            }
+        };
         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;
+                    addEquivalency(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)
+                    let 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('.')) {
+                        // Special case: If hookCallPath is a callback scope (cyScope pattern),
+                        // trace through it to find what the callback actually returns.
+                        // This handles useState(() => { return prop; }) patterns.
+                        const cyScopeMatch = hookCallPath.match(/^(cyScope\d+)\(\)$/);
+                        if (cyScopeMatch) {
+                            // Use the equivalency database to trace the callback's return value
+                            // to its actual source (e.g., viewModeFromUrl -> segments -> params -> useParams)
+                            const dbEntry = this.getEquivalenciesDatabaseEntry(scopeNode.name, // Component scope
+                            path);
+                            if (dbEntry?.sourceCandidates?.length > 0) {
+                                // Use the traced source instead of the callback scope
+                                hookCallPath = dbEntry.sourceCandidates[0].schemaPath;
+                            }
+                        }
+                        addEquivalency(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
+                ) {
+                    // Skip bare "returnValue" from child scopes — this is the child's return value,
+                    // not a meaningful data source path in the parent scope
+                    if (equivalentValue.schemaPath === 'returnValue' &&
+                        equivalentValue.scopeNodeName !==
+                            this.scopeTreeManager.getRootName()) {
+                        continue;
+                    }
+                    // Add equivalency (will accumulate if multiple values for OR expressions)
+                    addEquivalency(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
+                ) {
+                    addEquivalency(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
+                ) {
+                    addEquivalency(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)
+                ) {
+                    // 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
+                        addEquivalency(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
+                        // Root scope values take precedence over child scope values
+                        if (!(path in equivalentSignatureVariables)) {
+                            addEquivalency(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
+        // Helper function to resolve a single source path using equivalencies
+        const resolveSourcePath = (sourcePath, equivMap) => {
+            // Extract base variable from the path
+            const dotIndex = sourcePath.indexOf('.');
+            const bracketIndex = sourcePath.indexOf('[');
+            let baseVar;
+            let rest;
+            if (dotIndex === -1 && bracketIndex === -1) {
+                baseVar = sourcePath;
+                rest = '';
+            }
+            else if (dotIndex === -1) {
+                baseVar = sourcePath.slice(0, bracketIndex);
+                rest = sourcePath.slice(bracketIndex);
+            }
+            else if (bracketIndex === -1) {
+                baseVar = sourcePath.slice(0, dotIndex);
+                rest = sourcePath.slice(dotIndex);
+            }
+            else {
+                const firstIndex = Math.min(dotIndex, bracketIndex);
+                baseVar = sourcePath.slice(0, firstIndex);
+                rest = sourcePath.slice(firstIndex);
+            }
+            // Look up the base variable in equivalencies
+            if (baseVar in equivMap && equivMap[baseVar] !== sourcePath) {
+                const baseResolved = equivMap[baseVar];
+                // Skip if baseResolved is an array (handle later)
+                if (Array.isArray(baseResolved))
+                    return null;
+                // If it resolves to a signature path, build the full resolved path
+                if (baseResolved.startsWith('signature[') ||
+                    baseResolved.includes('()')) {
+                    if (baseResolved.endsWith('()')) {
+                        return baseResolved + '.functionCallReturnValue' + rest;
+                    }
+                    return baseResolved + rest;
+                }
+            }
+            return null;
+        };
+        for (let iteration = 0; iteration < maxIterations; iteration++) {
+            let changed = false;
+            for (const [varName, sourcePathOrArray] of Object.entries(equivalentSignatureVariables)) {
+                // Handle arrays (OR expressions) by resolving each element
+                if (Array.isArray(sourcePathOrArray)) {
+                    const resolvedArray = [];
+                    let arrayChanged = false;
+                    for (const sourcePath of sourcePathOrArray) {
+                        // Try to resolve this path using transitive resolution
+                        const resolved = resolveSourcePath(sourcePath, equivalentSignatureVariables);
+                        if (resolved && resolved !== sourcePath) {
+                            resolvedArray.push(resolved);
+                            arrayChanged = true;
+                        }
+                        else {
+                            resolvedArray.push(sourcePath);
+                        }
+                    }
+                    if (arrayChanged) {
+                        equivalentSignatureVariables[varName] = resolvedArray;
+                        changed = true;
+                    }
+                    continue;
+                }
+                const sourcePath = sourcePathOrArray;
+                // 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) => /^\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];
+                            // Skip if baseResolved is an array (OR expression)
+                            if (Array.isArray(baseResolved))
+                                continue;
+                            // 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;
+                                }
+                            }
+                        }
+                    }
+                    // Fix 38: Handle cyScope lazy initializer return values
+                    // When we have viewMode -> cyScope20(), trace through to find what cyScope20 returns.
+                    // The lazy initializer's return value should be the controllable data source.
+                    // Pattern: cyScopeN() where N is a number
+                    const cyScopeMatch = sourcePath.match(/^(cyScope\d+)\(\)$/);
+                    if (cyScopeMatch) {
+                        const cyScopeName = cyScopeMatch[1];
+                        const cyScopeNode = this.scopeNodes[cyScopeName];
+                        if (cyScopeNode?.equivalencies) {
+                            // Look for returnValue equivalency in the cyScope
+                            const returnValueEquivs = cyScopeNode.equivalencies['returnValue'];
+                            if (returnValueEquivs && returnValueEquivs.length > 0) {
+                                // Get the first return value source
+                                const returnSource = returnValueEquivs[0].schemaPath;
+                                // If the return source is a simple variable (not a complex path),
+                                // resolve varName directly to that variable
+                                if (returnSource &&
+                                    !returnSource.includes('(') &&
+                                    !returnSource.includes('[')) {
+                                    // Update varName to point to the return source
+                                    if (equivalentSignatureVariables[varName] !== returnSource) {
+                                        equivalentSignatureVariables[varName] = returnSource;
+                                        changed = true;
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    continue;
+                }
+                // Check if the source path starts with a variable that's also in the map
+                const dotIndex = sourcePath.indexOf('.');
+                let baseVar;
+                let rest;
+                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) {
+                    // Handle array case (OR expressions) - use first element
+                    const rawBaseResolved = equivalentSignatureVariables[baseVar];
+                    const baseResolved = Array.isArray(rawBaseResolved)
+                        ? rawBaseResolved[0]
+                        : rawBaseResolved;
+                    if (!baseResolved)
+                        continue;
+                    // 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;
     }
     getVariableInfo(variableName, scopeName, final) {
-        const scopeNode = this.getScopeOrFunctionCallInfo(scopeName ?? this.scopeTree.name);
+        const scopeNode = this.getScopeOrFunctionCallInfo(scopeName ?? this.scopeTreeManager.getRootName());
         if (!scopeNode)
             return;
         let equivalents = scopeNode.equivalencies[variableName];
@@ -2028,8 +3660,13 @@ export class ScopeDataStructure {
             });
             return { ...acc, ...filterdSchema };
         }, {});
-        const tempScopeNode = this.createTempScopeNode(scopeName ?? this.scopeTree.name, relevantSchema);
+        const tempScopeNode = this.createTempScopeNode(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,
             equivalentTo: equivalents,
@@ -2037,66 +3674,1212 @@ export class ScopeDataStructure {
         };
     }
     getExternalFunctionCalls() {
-        return this.externalFunctionCalls;
+        // 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.
+        const rootScopeName = this.scopeTreeManager.getRootName();
+        const rootSchema = this.scopeNodes[rootScopeName]?.schema ?? {};
+        return this.externalFunctionCalls.map((efc) => {
+            const cleaned = this.cleanCyScopeFromFunctionCallInfo(efc);
+            return this.filterConflatedExternalPaths(cleaned, rootSchema);
+        });
+    }
+    /**
+     * Filters out conflated paths from external function call schemas.
+     *
+     * When multiple useState(false) calls create equivalency conflation during
+     * Phase 1 analysis, standalone boolean state variables (like showWorkoutForm,
+     * showGoalForm) can bleed into external function call schemas as sub-properties
+     * of unrelated data fields (like data[].activity_type.showWorkoutForm).
+     *
+     * Detection: group sub-properties by parent path. If 2+ sub-properties of
+     * the same parent all match standalone root scope variable names, treat them
+     * as conflation artifacts and remove them.
+     */
+    filterConflatedExternalPaths(efc, rootSchema) {
+        // Build a set of top-level root scope variable names (simple names, no dots/brackets)
+        const topLevelRootVars = new Set();
+        for (const key of Object.keys(rootSchema)) {
+            if (!key.includes('.') && !key.includes('[')) {
+                topLevelRootVars.add(key);
+            }
+        }
+        if (topLevelRootVars.size === 0)
+            return efc;
+        // Group sub-property matches by their parent path.
+        // For a path like "...data[].activity_type.showWorkoutForm",
+        // parent = "...data[].activity_type", child = "showWorkoutForm"
+        const parentToConflatedKeys = new Map();
+        for (const key of Object.keys(efc.schema)) {
+            const lastDot = key.lastIndexOf('.');
+            if (lastDot === -1)
+                continue;
+            const parent = key.substring(0, lastDot);
+            const child = key.substring(lastDot + 1);
+            // Skip array access or function call patterns
+            if (child.includes('[') || child.includes('('))
+                continue;
+            // Only consider paths inside array element chains (contains []).
+            // Direct children of functionCallReturnValue are legitimate destructured
+            // return values, not conflation. Conflation happens deeper in the chain
+            // when array element fields get corrupted sub-properties.
+            if (!parent.includes('['))
+                continue;
+            if (topLevelRootVars.has(child)) {
+                if (!parentToConflatedKeys.has(parent)) {
+                    parentToConflatedKeys.set(parent, []);
+                }
+                parentToConflatedKeys.get(parent).push(key);
+            }
+        }
+        // Only filter when 2+ sub-properties of the same parent match root scope vars.
+        // This threshold avoids false positives from coincidental name matches.
+        const keysToRemove = new Set();
+        const parentsToRestore = new Set();
+        for (const [parent, conflatedKeys] of parentToConflatedKeys) {
+            if (conflatedKeys.length >= 2) {
+                for (const key of conflatedKeys) {
+                    keysToRemove.add(key);
+                }
+                parentsToRestore.add(parent);
+            }
+        }
+        if (keysToRemove.size === 0)
+            return efc;
+        // Create a new schema without the conflated paths
+        const newSchema = {};
+        for (const [key, value] of Object.entries(efc.schema)) {
+            if (keysToRemove.has(key))
+                continue;
+            // Restore parent type: if it was changed to "object" because of conflated
+            // sub-properties, and now all those sub-properties are removed, change it
+            // back to "unknown" (we don't know the original type)
+            if (parentsToRestore.has(key) && value === 'object') {
+                // Check if there are any remaining sub-properties
+                const hasRemainingSubProps = Object.keys(efc.schema).some((k) => !keysToRemove.has(k) &&
+                    k !== key &&
+                    (k.startsWith(key + '.') || k.startsWith(key + '[')));
+                newSchema[key] = hasRemainingSubProps ? value : 'unknown';
+            }
+            else {
+                newSchema[key] = value;
+            }
+        }
+        return { ...efc, schema: newSchema };
+    }
+    /**
+     * Cleans cyScope placeholder references from a FunctionCallInfo.
+     * Replaces cyScopeN() with the actual callback text in:
+     * - callSignature
+     * - allCallSignatures
+     * - schema keys
+     */
+    cleanCyScopeFromFunctionCallInfo(efc) {
+        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;
+        }
+        // Create cleaned copy
+        const cleaned = { ...efc };
+        // Clean callSignature
+        cleaned.callSignature = this.replaceCyScopeInString(efc.callSignature);
+        // Clean allCallSignatures
+        if (efc.allCallSignatures) {
+            cleaned.allCallSignatures = efc.allCallSignatures.map((sig) => this.replaceCyScopeInString(sig));
+        }
+        // Clean schema keys
+        if (efc.schema) {
+            cleaned.schema = this.replaceCyScopePlaceholders(efc.schema);
+        }
+        // Clean callSignatureToVariable keys
+        if (efc.callSignatureToVariable) {
+            cleaned.callSignatureToVariable = Object.entries(efc.callSignatureToVariable).reduce((acc, [key, value]) => {
+                acc[this.replaceCyScopeInString(key)] = value;
+                return acc;
+            }, {});
+        }
+        return cleaned;
+    }
+    /**
+     * 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]+)
+     */
+    replaceCyScopeInString(str) {
+        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);
+        }
+        // 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) {
+        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) {
+        // 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() {
+        return this.rawConditionalEffects;
+    }
+    /**
+     * Add compound conditionals from AST analysis.
+     * Called during scope analysis to collect grouped conditions (e.g., a && b && c).
+     */
+    addCompoundConditionals(compounds) {
+        // 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() {
+        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) {
+        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() {
+        const enriched = {};
+        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;
+                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() {
+        const enriched = {};
+        console.log(`[getEnrichedConditionalUsages] Processing ${Object.keys(this.rawConditionalUsages).length} conditional paths: [${Object.keys(this.rawConditionalUsages).join(', ')}]`);
+        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;
+            if (explanation.source) {
+                const { scope, path: sourcePath } = explanation.source;
+                // Build initial path — avoid redundant prefix when path already contains the scope call
+                let fullPath;
+                if (sourcePath.startsWith(`${scope}(`)) {
+                    fullPath = sourcePath;
+                }
+                else {
+                    fullPath = `${scope}.${sourcePath}`;
+                }
+                sourceDataPath = fullPath;
+                console.log(`[getEnrichedConditionalUsages] "${path}" explainPath → scope="${scope}", sourcePath="${sourcePath}" → sourceDataPath="${sourceDataPath}"`);
+            }
+            else {
+                console.log(`[getEnrichedConditionalUsages] "${path}" explainPath → no source found`);
+            }
+            // If explainPath didn't find a useful external source (e.g., it traced to
+            // useState or just to the component scope itself), check sourceEquivalencies
+            // for an external function call source like a fetch call
+            const hasExternalSource = sourceDataPath?.includes('.functionCallReturnValue');
+            if (!hasExternalSource) {
+                console.log(`[getEnrichedConditionalUsages] "${path}" no external source (sourceDataPath="${sourceDataPath}"), checking sourceEquivalencies fallback...`);
+                const sourceEquiv = this.getSourceEquivalencies();
+                const returnValueKey = `returnValue.${path}`;
+                const sources = sourceEquiv[returnValueKey];
+                if (sources) {
+                    console.log(`[getEnrichedConditionalUsages] "${path}" sourceEquivalencies["${returnValueKey}"] has ${sources.length} sources: [${sources.map((s) => s.schemaPath).join(', ')}]`);
+                    const externalSource = sources.find((s) => s.schemaPath.includes('.functionCallReturnValue') &&
+                        !s.schemaPath.startsWith('useState('));
+                    if (externalSource) {
+                        console.log(`[getEnrichedConditionalUsages] "${path}" sourceEquivalencies fallback found external source: "${externalSource.schemaPath}"`);
+                        sourceDataPath = externalSource.schemaPath;
+                    }
+                    else {
+                        console.log(`[getEnrichedConditionalUsages] "${path}" sourceEquivalencies fallback found no external function call source`);
+                    }
+                }
+                else {
+                    console.log(`[getEnrichedConditionalUsages] "${path}" sourceEquivalencies["${returnValueKey}"] not found`);
+                }
+            }
+            console.log(`[getEnrichedConditionalUsages] "${path}" FINAL sourceDataPath="${sourceDataPath ?? '(none)'}" (${usages.length} usages)`);
+            enriched[path] = usages.map((usage) => ({
+                ...usage,
+                sourceDataPath,
+            }));
+        }
+        return enriched;
+    }
+    /**
+     * Add JSX rendering usages from AST analysis.
+     * These track arrays rendered via .map() and strings interpolated in JSX.
+     */
+    addJsxRenderingUsages(usages) {
+        // Add usages, avoiding duplicates based on path and renderingType
+        for (const usage of usages) {
+            const exists = this.rawJsxRenderingUsages.some((existing) => existing.path === usage.path &&
+                existing.renderingType === usage.renderingType);
+            if (!exists) {
+                this.rawJsxRenderingUsages.push(usage);
+            }
+        }
+    }
+    /**
+     * Get JSX rendering usages collected during analysis.
+     */
+    getJsxRenderingUsages() {
+        return this.rawJsxRenderingUsages;
+    }
     toSerializable() {
-        // Helper to convert ScopeVariable to SerializableScopeVariable
+        // Helper to clean cyScope and cyDuplicateKey from a string for output
+        const cleanCyScope = (str) => this.replaceCyScopeInString(str).replace(/::cyDuplicateKey\d+::/g, '');
+        // Helper to convert ScopeVariable to SerializableScopeVariable (with cyScope cleaned)
         const toSerializableVariable = (vars) => vars.map((v) => ({
-            scopeNodeName: v.scopeNodeName,
-            schemaPath: v.schemaPath,
+            scopeNodeName: cleanCyScope(v.scopeNodeName),
+            schemaPath: cleanCyScope(v.schemaPath),
         }));
+        // Helper to clean cyScope from all keys in a schema
+        const cleanSchemaKeys = (schema) => {
+            return Object.entries(schema).reduce((acc, [key, value]) => {
+                acc[cleanCyScope(key)] = value;
+                return acc;
+            }, {});
+        };
         // Helper to get function result for a given function name
         const getFunctionResult = (functionName) => {
             return {
-                signature: this.getFunctionSignature({ functionName }) ?? {},
-                signatureWithUnknowns: this.getFunctionSignature({ functionName, fillInUnknowns: true }) ??
-                    {},
-                returnValue: this.getReturnValue({ functionName }) ?? {},
-                returnValueWithUnknowns: this.getReturnValue({ functionName, fillInUnknowns: true }) ?? {},
+                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]) => {
-                    acc[key] = toSerializableVariable(vars);
+                    // Clean cyScope from the key as well as variable properties
+                    acc[cleanCyScope(key)] = toSerializableVariable(vars);
                     return acc;
                 }, {}),
                 sourceEquivalencies: Object.entries(this.getSourceEquivalencies(functionName) ?? {}).reduce((acc, [key, vars]) => {
-                    acc[key] = toSerializableVariable(vars);
+                    // Clean cyScope from the key as well as variable properties
+                    acc[cleanCyScope(key)] = toSerializableVariable(vars);
                     return acc;
                 }, {}),
                 environmentVariables: this.getEnvironmentVariables(),
             };
         };
-        // Convert external function calls
-        const externalFunctionCalls = 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;
-                }, {})
-                : undefined,
-        }));
+        // 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 = 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;
+            // 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 = {};
+                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 = {};
+                // 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 = {};
+                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 = {};
+                        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 = {};
+                    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;
+                }
+            }
+            // Enrich the schema with inferred types by applying fillInSchemaGapsAndUnknowns.
+            // This ensures the serialized schema has the same type inference as getReturnValue().
+            // Without this, evidence like "entities[].analyses: array" becomes "unknown".
+            const enrichedSchema = { ...efc.schema };
+            const tempScopeNode = {
+                name: efc.name,
+                schema: enrichedSchema,
+                equivalencies: efc.equivalencies ?? {},
+            };
+            fillInSchemaGapsAndUnknowns(tempScopeNode, true);
+            return {
+                name: efc.name,
+                callSignature: efc.callSignature,
+                callScope: efc.callScope,
+                schema: enrichedSchema,
+                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;
+                    }, {})
+                    : 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) => {
+            // Group entries by base function name (without type parameters)
+            const groups = new Map();
+            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 = [];
+                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();
+                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 = {};
+                    for (const [varName, varSchema] of Object.entries(entry.perVariableSchemas)) {
+                        const filteredVarSchema = {};
+                        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
+        // Get results for each external function (use cleaned calls for consistency)
         const functionResults = {};
-        for (const efc of this.externalFunctionCalls) {
+        for (const efc of cleanedExternalCalls) {
             functionResults[efc.name] = getFunctionResult(efc.name);
         }
-        // Get equivalent signature variables
-        const equivalentSignatureVariables = this.getEquivalentSignatureVariables();
         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;
+        // Get JSX rendering usages (arrays via .map(), strings via interpolation)
+        const jsxRenderingUsages = this.rawJsxRenderingUsages.length > 0
+            ? this.rawJsxRenderingUsages
+            : undefined;
         return {
-            externalFunctionCalls,
+            externalFunctionCalls: deduplicatedExternalFunctionCalls,
             rootFunction,
             functionResults,
             equivalentSignatureVariables,
             environmentVariables,
+            conditionalUsages,
+            conditionalEffects,
+            compoundConditionals,
+            childBoundaryGatingConditions,
+            jsxRenderingUsages,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 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, path) {
+        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) {
+        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,
+                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;
+                }, {});
+            }
+            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, path, maxDepth = 20) {
+        const chain = [];
+        const visited = new Set();
+        const queue = [
+            { 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, pattern) {
+        const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
+        if (!scopeNode)
+            return [];
+        const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+        const results = [];
+        // 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, path) {
+        const scopeNode = this.getScopeOrFunctionCallInfo(scopeName);
+        const possibleReasons = [];
+        const suggestions = [];
+        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() {
+        const byReason = {};
+        const byScope = {};
+        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() {
+        const issues = [];
+        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();
+                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;
+    }
 }
 //# sourceMappingURL=ScopeDataStructure.js.map