@codeyam/codeyam-cli 0.1.0-staging.28f73cf → 0.1.0-staging.596f0eb

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

@@ -204,6 +204,23 @@ export interface FunctionCallInfo {
   schema?: Record<string, string>;
   /** Traces argument data back to original source */
   equivalencies?: Record<string, ScopeVariable[]>;
+  /**
+   * All call signatures that were merged into this entry.
+   * When multiple method calls on the same object (e.g., logger.info, logger.debug)
+   * are encountered, they get merged into one FunctionCallInfo but we track all signatures.
+   */
+  allCallSignatures?: string[];
+  /**
+   * Variable names that receive the return value of each call.
+   * For example, in `const result1 = db.select(query1)`, the receiving variable is 'result1'.
+   * This enables generating separate mock data for each call site.
+   */
+  receivingVariableNames?: string[];
+  /**
+   * Maps each call signature to the variable that receives its return value.
+   * For example: { "db.select(query1)": "result1", "db.select(query2)": "result2" }
+   */
+  callSignatureToVariable?: Record<string, string>;
 }
 
 /**
@@ -301,6 +318,7 @@ const ALLOWED_EQUIVALENCY_REASONS = new Set([
   '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
 ]);
 
@@ -913,13 +931,69 @@ export class ScopeDataStructure {
       }
     }
 
+    // Skip self-referential equivalencies that would create infinite loops.
+    // Case 1: Direct self-reference (path === equivalentPath)
+    // FunctionCallManager adds equivalency(subPath, subPath, externalFunctionName, ...)
+    // For simple calls like buildBranchFileMap(), this is fine.
+    // But for chained calls like query.where().where().where(), each method call adds
+    // a .functionCallReturnValue segment, and the equivalency processing creates an infinite loop.
+    // We detect chained calls by counting .functionCallReturnValue occurrences in the path.
+    if (
+      path === equivalentPath &&
+      equivalencyReason === 'equivalency to external function call'
+    ) {
+      // Count how many .functionCallReturnValue segments are in the path
+      const functionCallReturnValueCount = (
+        path.match(/\.functionCallReturnValue/g) || []
+      ).length;
+      // Skip if there are multiple chained calls (2+ .functionCallReturnValue segments)
+      if (functionCallReturnValueCount >= 2) {
+        return;
+      }
+    }
+
+    // Case 2: Circular reference where equivalentPath contains path as a prefix
+    // e.g., path="query" and equivalentPath="query.where(...).functionCallReturnValue"
+    // This happens with method chaining patterns where a variable is reassigned to
+    // the result of a method call on itself: query = query.where(...)
+    // Resolving this equivalency would require resolving query first, creating infinite recursion.
+    if (
+      equivalentPath.startsWith(path + '.') ||
+      equivalentPath.startsWith(path + '(')
+    ) {
+      return;
+    }
+
     if (!equivalentScopeName) {
-      console.warn('Debug Propagation: missing equivalent scope name', {
-        path,
-        equivalentPath,
-        equivalentScopeName,
-        scopeNodeName: scopeNode.name,
-      });
+      console.error(
+        'CodeYam Error: Missing equivalent scope name - FULL CONTEXT:',
+        JSON.stringify(
+          {
+            path,
+            equivalentPath,
+            equivalentScopeName,
+            scopeNodeName: scopeNode.name,
+            equivalencyReason,
+            tree: scopeNode.tree,
+            equivalencyValueChain: equivalencyValueChain?.map((ev) => ({
+              id: ev.id,
+              source: ev.source,
+              reason: ev.reason,
+              currentPath: ev.currentPath,
+              previousPath: ev.previousPath,
+            })),
+            scopeNodeFunctionCalls: scopeNode.functionCalls?.map((fc) => ({
+              name: fc.name,
+              callSignature: fc.callSignature,
+              callScope: fc.callScope,
+            })),
+            instantiatedVariables: scopeNode.instantiatedVariables,
+            parentInstantiatedVariables: scopeNode.parentInstantiatedVariables,
+          },
+          null,
+          2,
+        ),
+      );
       throw new Error('CodeYam Error: Missing equivalent scope name');
     }
 
@@ -1086,6 +1160,22 @@ export class ScopeDataStructure {
           ...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 =
@@ -1273,6 +1363,23 @@ export class ScopeDataStructure {
     return this.pathManager.joinPathParts(pathParts);
   }
 
+  /**
+   * Extracts the root variable name from a path.
+   * E.g., "collected[]" -> "collected", "foo.bar" -> "foo", "collected[0]" -> "collected"
+   */
+  extractRootVariable(path: string): string | null {
+    const parts = this.splitPath(path);
+    if (parts.length === 0) return null;
+
+    const firstPart = parts[0];
+    // Strip array notation: "collected[]" -> "collected", "collected[0]" -> "collected"
+    const bracketIndex = firstPart.indexOf('[');
+    if (bracketIndex > 0) {
+      return firstPart.substring(0, bracketIndex);
+    }
+    return firstPart;
+  }
+
   // PRIVATE METHODS //
 
   private uniqueId(params: {
@@ -1368,6 +1475,41 @@ export class ScopeDataStructure {
     const { isolatedStructure, isolatedEquivalentVariables } =
       scopeNode.analysis;
 
+    // DEBUG: Log all equivalencies related to useFetcher
+    if (
+      Object.keys(isolatedEquivalentVariables || {}).some(
+        (k) => k.includes('Fetcher') || k.includes('fetcher'),
+      )
+    ) {
+      console.log(
+        'CodeYam DEBUG determineEquivalenciesAndBuildSchema:',
+        JSON.stringify(
+          {
+            scopeNodeName: scopeNode.name,
+            fetcherEquivalencies: Object.entries(
+              isolatedEquivalentVariables || {},
+            )
+              .filter(
+                ([k, v]) =>
+                  k.includes('Fetcher') ||
+                  k.includes('fetcher') ||
+                  String(v).includes('Fetcher') ||
+                  String(v).includes('fetcher'),
+              )
+              .reduce(
+                (acc, [k, v]) => {
+                  acc[k] = v;
+                  return acc;
+                },
+                {} as Record<string, string>,
+              ),
+          },
+          null,
+          2,
+        ),
+      );
+    }
+
     const allPaths = Array.from(
       new Set([
         ...Object.keys(isolatedStructure || {}),
@@ -1394,6 +1536,47 @@ export class ScopeDataStructure {
           'original equivalency',
         );
 
+        // Propagate equivalencies involving parent-scope variables to those parent scopes.
+        // This handles patterns like: collected.push({...entity}) where 'collected' is defined
+        // in a parent scope. The equivalency collected[] -> push().signature[0] needs to be
+        // visible when tracing from the parent scope.
+        const rootVariable = this.extractRootVariable(path);
+        const equivalentRootVariable =
+          this.extractRootVariable(equivalentValue);
+
+        // Skip propagation for self-referential reassignment patterns like:
+        //   x = x.method().functionCallReturnValue
+        // where the path IS the variable itself (not a sub-path like x[] or x.prop).
+        // These create circular references since both sides reference the same variable.
+        //
+        // But DO propagate for patterns like collected[] -> collected.push(...).signature[0]
+        // where the path has additional segments beyond the root variable.
+        const pathIsJustRootVariable = path === rootVariable;
+        const isSelfReferentialReassignment =
+          pathIsJustRootVariable && rootVariable === equivalentRootVariable;
+
+        if (
+          rootVariable &&
+          !isSelfReferentialReassignment &&
+          scopeNode.parentInstantiatedVariables?.includes(rootVariable)
+        ) {
+          // Find the parent scope where this variable is defined
+          for (const parentScopeName of scopeNode.tree || []) {
+            const parentScope = this.scopeNodes[parentScopeName];
+            if (parentScope?.instantiatedVariables?.includes(rootVariable)) {
+              // Add the equivalency to the parent scope as well
+              this.addEquivalency(
+                path,
+                equivalentValue,
+                scopeNode.name, // The equivalent path's scope remains the child scope
+                parentScope, // But store it in the parent scope's equivalencies
+                'propagated parent-variable equivalency',
+              );
+              break;
+            }
+          }
+        }
+
         // Propagate sub-property equivalencies when the equivalentValue is a simple variable
         // that has sub-properties defined in the isolatedEquivalentVariables.
         // This handles cases like: dataItem={{ structure: completeDataStructure }}
@@ -1470,6 +1653,16 @@ export class ScopeDataStructure {
             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);
         }
       }
     }
@@ -1540,6 +1733,86 @@ export class ScopeDataStructure {
     }
   }
 
+  /**
+   * Tracks which variable receives the return value of a function call.
+   *
+   * When we encounter an equivalency like:
+   *   result1 -> db.select(query1).functionCallReturnValue
+   *
+   * This method extracts the call signature (db.select(query1)) and maps it
+   * to the receiving variable (result1) on the corresponding FunctionCallInfo.
+   *
+   * This enables generating separate mock data for each call site when the same
+   * function is called multiple times with different arguments.
+   */
+  private trackReceivingVariable(
+    receivingVariable: string,
+    equivalentValue: string,
+  ): void {
+    // Extract the call signature by finding the .functionCallReturnValue part
+    // and taking everything before it
+    // Handles both:
+    //   "db.select(query1).functionCallReturnValue" -> "db.select(query1)"
+    //   "db.query('users').functionCallReturnValue.data" -> "db.query('users')"
+    const funcReturnIdx = equivalentValue.indexOf('.functionCallReturnValue');
+    if (funcReturnIdx === -1) {
+      return;
+    }
+    const callSignature = equivalentValue.substring(0, funcReturnIdx);
+
+    // Skip if the receiving variable is not a simple identifier
+    // (e.g., skip if it's a path like "obj.property" or contains array access)
+    if (receivingVariable.includes('.') || receivingVariable.includes('[')) {
+      return;
+    }
+
+    // Find the FunctionCallInfo that matches this call signature
+    const searchKey = getFunctionCallRoot(callSignature);
+    const functionCallInfo =
+      this.getExternalFunctionCallsIndex().get(searchKey);
+
+    // DEBUG: Track useFetcher calls
+    if (searchKey === 'useFetcher' || callSignature.includes('useFetcher')) {
+      console.log(
+        'CodeYam DEBUG trackReceivingVariable:',
+        JSON.stringify(
+          {
+            receivingVariable,
+            equivalentValue,
+            callSignature,
+            searchKey,
+            foundFunctionCallInfo: !!functionCallInfo,
+            existingRecvVars: functionCallInfo?.receivingVariableNames,
+            existingCallSigToVar: functionCallInfo?.callSignatureToVariable,
+          },
+          null,
+          2,
+        ),
+      );
+    }
+
+    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.
    *
@@ -2890,6 +3163,40 @@ export class ScopeDataStructure {
     this.validateSchema(scopeNode, true, fillInUnknowns);
 
     const { schema } = scopeNode;
+
+    // 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 mergedSchema;
+    }
+
     return schema;
   }
 
@@ -3402,6 +3709,9 @@ export class ScopeDataStructure {
               {} as Record<string, SerializableScopeVariable[]>,
             )
           : undefined,
+        allCallSignatures: efc.allCallSignatures,
+        receivingVariableNames: efc.receivingVariableNames,
+        callSignatureToVariable: efc.callSignatureToVariable,
       }));
 
     // Get root function result

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

@@ -439,6 +439,27 @@ export default class FunctionCallManager implements EquivalencyManager {
             scopeNode,
             externalFunctionCallInfo,
           );
+        } else {
+          // Even if an entry exists, we need to register this call signature
+          // so it gets merged into allCallSignatures. This handles multiple
+          // calls to the same function (e.g., multiple useFetcher() calls).
+          const newFunctionCallInfo = {
+            name: functionCallRoot,
+            callSignature: functionCallSignature,
+            callScope: equivalencyValueChain[0].currentPath.scopeNodeName,
+            schema: {},
+            equivalencies: {},
+          };
+          if (traceId && debugLevel > 0) {
+            console.info(
+              'Debug Propagation: addFunctionCall external (merge)',
+              {
+                existingCallSignature: externalFunctionCallInfo.callSignature,
+                newCallSignature: functionCallSignature,
+              },
+            );
+          }
+          scopeDataStructure.addFunctionCall(scopeNode, newFunctionCallInfo);
         }
 
         if (traceId && debugLevel > 0) {
@@ -456,13 +477,22 @@ export default class FunctionCallManager implements EquivalencyManager {
 
         propagated = true;
 
-        scopeDataStructure.addEquivalency(
-          subPath,
-          subPath,
-          externalFunctionCallInfo.name,
-          scopeNode,
-          'equivalency to external function call',
-        );
+        // Skip self-referential equivalencies for chained external function calls.
+        // For chained calls like query.where().where(), each method call adds a
+        // .functionCallReturnValue segment. Processing these creates infinite loops.
+        // We only add the equivalency for simple calls (0-1 .functionCallReturnValue segments).
+        const functionCallReturnValueCount = (
+          subPath.match(/\.functionCallReturnValue/g) || []
+        ).length;
+        if (functionCallReturnValueCount < 2) {
+          scopeDataStructure.addEquivalency(
+            subPath,
+            subPath,
+            externalFunctionCallInfo.name,
+            scopeNode,
+            'equivalency to external function call',
+          );
+        }
 
         if (subPathParts[subPathParts.length - 1].startsWith('signature[')) {
           externalFunctionCallInfo.equivalencies[subPath] ||= [];

package/analyzer-template/packages/ai/src/lib/dataStructure/equivalencyManagers/frameworks/JavascriptFrameworkManager.ts

@@ -288,6 +288,18 @@ export class JavascriptFrameworkManager implements EquivalencyManager {
     let propagated = false;
     const mapFunction = mapCall.slice(4, -1); // remove 'map(' and ')'
 
+    // Extract the scope name from the map callback
+    // For named scopes like "cyScope12(...)", split('(')[0] gives "cyScope12"
+    // For inline arrow functions like "(item) => item.operation", split('(')[0] gives ""
+    const mapFunctionScopeName = mapFunction.split('(')[0];
+
+    // Skip if the map callback is an inline arrow function (no named scope)
+    // Inline arrow functions like "(item) => item.operation" aren't isolated as separate scopes
+    // so we can't create equivalencies referencing their scope name
+    if (!mapFunctionScopeName) {
+      return false;
+    }
+
     for (const [equivalentPath, equivalentValues] of Object.entries(
       scopeNode.equivalencies,
     )) {
@@ -317,7 +329,7 @@ export class JavascriptFrameworkManager implements EquivalencyManager {
             scopeDataStructure.addEquivalency(
               scopeDataStructure.joinPathParts(equivalentPathParts.slice(1)),
               'returnValue',
-              mapFunction.split('(')[0],
+              mapFunctionScopeName,
               scopeDataStructure.scopeNodes[equivalentPathParts[0]],
               '.map() function deconstruction',
               equivalencyValueChain,
@@ -327,7 +339,7 @@ export class JavascriptFrameworkManager implements EquivalencyManager {
             scopeDataStructure.addEquivalency(
               arrayEquivalent ? equivalentPath : `${equivalentPath}[]`,
               'returnValue',
-              mapFunction.split('(')[0],
+              mapFunctionScopeName,
               scopeNode,
               '.map() function deconstruction',
               equivalencyValueChain,

package/analyzer-template/packages/ai/src/lib/dataStructure/equivalencyManagers/frameworks/ReactFrameworkManager.ts

@@ -251,9 +251,9 @@ export class ReactFrameworkManager implements EquivalencyManager {
               equivalentPathParts[0].replace(existingFunctionName, ''),
             ...equivalentPathParts.slice(1),
           ]);
-          for (const equivalentValue of scopeNode.equivalencies[
-            equivalentPath
-          ]) {
+          const equivalenciesToReroute =
+            scopeNode.equivalencies[equivalentPath] ?? [];
+          for (const equivalentValue of equivalenciesToReroute) {
             scopeDataStructure.removeEquivalency(
               equivalentPath,
               equivalentValue,
@@ -273,7 +273,9 @@ export class ReactFrameworkManager implements EquivalencyManager {
           equivalentPath = newEquivalentPath;
         }
 
-        for (const equivalentValue of scopeNode.equivalencies[equivalentPath]) {
+        const equivalenciesToModify =
+          scopeNode.equivalencies[equivalentPath] ?? [];
+        for (const equivalentValue of equivalenciesToModify) {
           if (equivalentValue.scopeNodeName === useCallbackScopeInfoName) {
             modifiedEquivalencies = true;
             equivalentValue.scopeNodeName =

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

@@ -30,7 +30,13 @@ export const nonTransformingArrayMethodsSet = new Set([
   'reverse',
   'entries',
 ]);
-const isolatingArrayMethodsSet = new Set(['find', 'at', 'pop', 'shift']);
+const isolatingArrayMethodsSet = new Set([
+  'find',
+  'findLast', // Returns element like find, but from end
+  'at',
+  'pop',
+  'shift',
+]);
 
 // Methods that are ambiguous - used on both arrays and non-arrays (e.g., router.push, history.pop)
 // Don't infer array type from these alone without additional evidence
@@ -42,6 +48,12 @@ export const transformingArrayMethodsSet = new Set([
   'concat',
   'join',
   'some',
+  'every', // Returns boolean
+  'findIndex', // Returns number (index)
+  'findLastIndex', // Returns number (index from end)
+  'indexOf', // Returns number (index)
+  'lastIndexOf', // Returns number (index from end)
+  'includes', // Returns boolean
 ]);
 
 export const arrayMethodsSet = new Set([
@@ -225,6 +237,54 @@ export function clearAttributesFromMapping(
   clearAttributes(mapping, knownBasePaths);
 }
 
+/**
+ * Remove duplicate function calls (same function with different arguments) that have no return data.
+ * Example: setSelectedFilter(arg1) and setSelectedFilter(arg2) where neither has functionCallReturnValue
+ * These create invalid mock code when spread together (orphan spread statements).
+ *
+ * This is a targeted fix that can be called independently without the full clearAttributes logic,
+ * which was disabled in constructMockCode.ts due to side effects on array method calls.
+ */
+export function removeDuplicateFunctionCalls(
+  mapping: Record<string, string>,
+): void {
+  const allKeys = Object.keys(mapping);
+  const functionCallGroups: { [baseName: string]: string[] } = {};
+
+  for (const key of allKeys) {
+    // Only process paths that:
+    // 1. Are marked as 'function'
+    // 2. END with a function call (parentheses) - not just contain one somewhere
+    // 3. Are on an object path (contain '.')
+    if (mapping[key] === 'function' && key.endsWith(')') && key.includes('.')) {
+      // Extract base path + function name (without the arguments)
+      // e.g., "returnValue.setSelectedFilter(arg)" -> "returnValue.setSelectedFilter"
+      const baseName = key.replace(/\([^)]*\)$/, '');
+      functionCallGroups[baseName] ||= [];
+      functionCallGroups[baseName].push(key);
+    }
+  }
+
+  // For groups with multiple calls (same function, different args), remove those without return data
+  for (const baseName in functionCallGroups) {
+    const calls = functionCallGroups[baseName];
+    if (calls.length > 1) {
+      // Multiple calls to the same function with different arguments
+      for (const callPath of calls) {
+        // Check if this call has return data
+        const hasReturnData = allKeys.some(
+          (k: string) =>
+            k.startsWith(callPath + '.functionCallReturnValue') ||
+            k.startsWith(callPath + '.signature['),
+        );
+        if (!hasReturnData) {
+          delete mapping[callPath];
+        }
+      }
+    }
+  }
+}
+
 function transformPath({
   oldPath,
   newPath,
@@ -642,13 +702,16 @@ function handleFunctionMapping(
     }
 
     // Don't add [] element for ambiguous methods without other array evidence
+    // Also don't add [] if the path was already identified as a string type
     const methodName = getMethodName(lastPart);
     const isAmbiguousMethod = ambiguousArrayMethodsSet.has(methodName);
+    const isStringType = keyMapping[previousPath] === 'string';
     if (
       !isValidFunctionCall(previousPart) &&
       arrayMethodsSet.has(methodName) &&
       !keyMapping[previousPath + '[]'] &&
-      !isAmbiguousMethod
+      !isAmbiguousMethod &&
+      !isStringType
     ) {
       keyMapping[previousPath + '[]'] = 'unknown';
     }
@@ -901,6 +964,9 @@ function clearAttributes(
     }
   }
 
+  // Remove duplicate function calls (same function with different arguments) that have no return data
+  removeDuplicateFunctionCalls(mapping);
+
   for (const key in mapping) {
     const value = mapping[key];
     if (knownTypes.has(value)) {

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

@@ -26,7 +26,6 @@ export default function convertDotNotation(
     const parts = splitOutsideParenthesesAndArrays(rawPath);
     if (!parts || parts.length === 0) continue;
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let cursor: any = result;
 
     for (let i = 0; i < parts.length; i++) {
@@ -181,8 +180,9 @@ export default function convertDotNotation(
           if (!isSkippableLeafType(typ)) {
             cursor[key] = [typ];
           } else {
-            // structural/placeholder subtype — ensure array exists but don't clobber
-            if (!Array.isArray(cursor[key])) cursor[key] = [];
+            // structural/placeholder subtype — ensure array exists but don't clobber existing values
+            // Only create an array if nothing exists yet; preserve concrete types like 'string'
+            if (cursor[key] === undefined) cursor[key] = [];
           }
           i++; // consume '[]'
         } else {