@codeyam/codeyam-cli 0.1.0-staging.d0ad4ae → 0.1.0-staging.d57a578

package/analyzer-template/packages/ai/src/lib/extractCriticalDataKeys.ts

@@ -0,0 +1,120 @@
+import type { ExecutionFlow, ScenariosDataStructure } from '~codeyam/types';
+
+/**
+ * Extract the data structure keys that are critical for satisfying execution flow requirements.
+ *
+ * When generating scenario mock data, only a subset of the full dataForMocks structure
+ * is actually needed to satisfy the scenario's covered flows' requiredValues.
+ * This function identifies those critical keys so they can be processed with more focus
+ * (e.g., in a separate LLM call or prioritized in the prompt).
+ *
+ * @param dataForMocks - The full data structure schema
+ * @param executionFlows - All execution flows for the entity
+ * @param coveredFlowIds - The flow IDs covered by the current scenario
+ * @returns Array of top-level keys from dataForMocks that are referenced by the covered flows
+ */
+export function extractCriticalDataKeys(
+  dataForMocks: ScenariosDataStructure['dataForMocks'],
+  executionFlows: ExecutionFlow[],
+  coveredFlowIds: string[],
+): string[] {
+  if (!dataForMocks || typeof dataForMocks !== 'object') {
+    return [];
+  }
+
+  const dataKeys = Object.keys(dataForMocks);
+  const criticalKeys = new Set<string>();
+
+  // Get the covered flows
+  const coveredFlows = executionFlows.filter((flow) =>
+    coveredFlowIds.includes(flow.id),
+  );
+
+  // For each covered flow, check if any requiredValue references a dataForMocks key
+  for (const flow of coveredFlows) {
+    if (!flow.requiredValues) continue;
+
+    for (const rv of flow.requiredValues) {
+      const path = rv.attributePath;
+      if (!path) continue;
+
+      // Try to match the attributePath to a dataForMocks key
+      // The path format is: "functionCall().functionCallReturnValue.property"
+      // or: "functionCall<Type>().functionCallReturnValue.property"
+      // We need to extract the function call part and match it to a key
+
+      for (const key of dataKeys) {
+        if (pathMatchesKey(path, key)) {
+          criticalKeys.add(key);
+          break; // One match per requiredValue is enough
+        }
+      }
+    }
+  }
+
+  return Array.from(criticalKeys);
+}
+
+/**
+ * Check if an attributePath references a given dataForMocks key.
+ *
+ * Handles various path formats:
+ * - "useParams().functionCallReturnValue.*" matches "useParams()"
+ * - "useLoaderData<LoaderData>().functionCallReturnValue.data" matches "useLoaderData<LoaderData>()"
+ * - "useFetcher().data.success" matches "useFetcher()"
+ */
+function pathMatchesKey(attributePath: string, dataKey: string): boolean {
+  // Normalize both for comparison
+  // Remove .functionCallReturnValue from the path
+  const normalizedPath = attributePath.replace('.functionCallReturnValue', '');
+
+  // Check if the path starts with the key (exact match for function call keys)
+  if (normalizedPath.startsWith(dataKey)) {
+    // Ensure it's not a partial match (e.g., "use" shouldn't match "useState")
+    const afterKey = normalizedPath.slice(dataKey.length);
+    // Valid continuations: end of string, '.', or '['
+    if (
+      afterKey === '' ||
+      afterKey.startsWith('.') ||
+      afterKey.startsWith('[')
+    ) {
+      return true;
+    }
+  }
+
+  // Try matching without type parameters if needed
+  // e.g., "useLoaderData<LoaderData>()" should match attributePaths with same base
+  const keyWithoutTypes = removeTypeParameters(dataKey);
+  const pathWithoutTypes = removeTypeParameters(normalizedPath);
+
+  if (pathWithoutTypes.startsWith(keyWithoutTypes)) {
+    const afterKey = pathWithoutTypes.slice(keyWithoutTypes.length);
+    if (
+      afterKey === '' ||
+      afterKey.startsWith('.') ||
+      afterKey.startsWith('[')
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Remove type parameters from a function call string.
+ * e.g., "useLoaderData<LoaderData>()" -> "useLoaderData()"
+ */
+function removeTypeParameters(str: string): string {
+  // Match and remove <...> including nested angle brackets
+  let result = str;
+  let prevLength = 0;
+
+  // Keep removing until no more changes (handles nested generics)
+  while (result.length !== prevLength) {
+    prevLength = result.length;
+    result = result.replace(/<[^<>]*>/g, '');
+  }
+
+  return result;
+}

package/analyzer-template/packages/ai/src/lib/generateChangesEntityScenarioData.ts

@@ -63,12 +63,12 @@ async function generateChangesDataForScenario({
   if (
     deepEqual(structure, existingStructure) &&
     deepEqual(
-      scenario.metadata.keyAttributeInstructions,
-      existingScenario.metadata.keyAttributeInstructions,
+      scenario.metadata?.coveredFlows,
+      existingScenario?.metadata?.coveredFlows,
     )
   ) {
     console.log(
-      "CodeYam: No changes in scenario's structure or keyAttributeInstructions - returning existing scenario data",
+      "CodeYam: No changes in scenario's structure or coveredFlows - returning existing scenario data",
       {
         analysisId: scenario.analysisId,
         scenarioId: scenario.id,
@@ -99,6 +99,7 @@ async function generateChangesDataForScenario({
       prompt = generateEntityScenarioDataGenerator(
         structure,
         scenario,
+        undefined, // executionFlows - not available in changes context
         defaultScenarioData,
         incompleteResponse,
       );

package/analyzer-template/packages/ai/src/lib/generateChangesEntityScenarios.ts

@@ -5,27 +5,19 @@ import generateChangesEntityScenariosGenerator from './promptGenerators/generate
 import {
   Analysis,
   Entity,
+  ExecutionFlow,
   ReadonlyAnalysisMap,
   Scenario,
 } from '~codeyam/types';
 import { ScenarioResult } from './generateEntityScenarios';
-import findMatchingAttribute from './findMatchingAttribute';
 import { awsLog } from '~codeyam/utils';
 import { sanitizePlaywrightInstructions } from './validatePlaywrightInstructions';
-import gatherRelevantDependentKeyAttributes from './gatherRelevantDependentKeyAttributes';
 import { AI, DEFAULT_LARGER_MODEL, parseJsonSafe } from '~codeyam/ai';
 
-interface ModifiedKeyAttribute {
-  keyAttribute: Analysis['metadata']['keyAttributes'][0];
-  newSourceLocations: Analysis['metadata']['keyAttributes'][0]['sourceLocations'];
-}
-
 interface GenerateChangesEntityScenariosArgs {
   entity: Entity;
-  keyAttributes: Analysis['metadata']['keyAttributes'];
-  addedKeyAttributes: Analysis['metadata']['keyAttributes'];
-  removedKeyAttributes: Analysis['metadata']['keyAttributes'];
-  modifiedKeyAttributes?: ModifiedKeyAttribute[];
+  executionFlows?: ExecutionFlow[];
+  previousExecutionFlows?: ExecutionFlow[];
   dependentAnalyses?: ReadonlyAnalysisMap;
   existingScenarios: Scenario[];
   commitDiff: string;
@@ -39,11 +31,8 @@ const DEFAULT_SCENARIO_NAME = 'Default Scenario';
 
 export default async function generateChangesEntityScenarios({
   entity,
-  keyAttributes,
-  addedKeyAttributes,
-  removedKeyAttributes,
-  modifiedKeyAttributes,
-  dependentAnalyses,
+  executionFlows,
+  previousExecutionFlows,
   existingScenarios,
   commitDiff,
   analysis,
@@ -51,16 +40,22 @@ export default async function generateChangesEntityScenarios({
   model,
   changedDataStructureFields = [],
 }: GenerateChangesEntityScenariosArgs) {
-  const relevantDependentKeyAttributes = gatherRelevantDependentKeyAttributes(
-    entity,
-    analysis.metadata.mergedDataStructure,
-    dependentAnalyses,
+  // Determine added/removed flows
+  const currentFlowIds = new Set((executionFlows ?? []).map((f) => f.id));
+  const previousFlowIds = new Set(
+    (previousExecutionFlows ?? []).map((f) => f.id),
   );
+
+  const addedFlows =
+    executionFlows?.filter((f) => !previousFlowIds.has(f.id)) ?? [];
+  const removedFlows =
+    previousExecutionFlows?.filter((f) => !currentFlowIds.has(f.id)) ?? [];
+
+  // If no changes, return existing scenarios
   if (
-    (!addedKeyAttributes || addedKeyAttributes.length === 0) &&
-    (!removedKeyAttributes || removedKeyAttributes.length === 0) &&
-    !existingScenarios.some((s) => s.metadata?.playwrightInstructions) &&
-    Object.keys(relevantDependentKeyAttributes).length === 0
+    addedFlows.length === 0 &&
+    removedFlows.length === 0 &&
+    !existingScenarios.some((s) => s.metadata?.playwrightInstructions)
   ) {
     return { scenarios: existingScenarios };
   }
@@ -69,22 +64,20 @@ export default async function generateChangesEntityScenarios({
     `CodeYam: Generating ${error ? 'error ' : ''}changes entity scenarios`,
     {
       filePath: entity.filePath,
-      entityNam: entity.name,
-      analysis: analysis.id,
-      keyAttributes: keyAttributes.map((a) => a.externalPath),
-      addedKeyAttributes: addedKeyAttributes?.map((a) => a.externalPath),
-      removedKeyAttributes: removedKeyAttributes?.map((a) => a.externalPath),
+      entityName: entity.name,
+      analysisId: analysis.id,
+      currentFlowCount: executionFlows?.length ?? 0,
+      addedFlows: addedFlows.map((f) => f.id),
+      removedFlows: removedFlows.map((f) => f.id),
     },
   );
 
   const prompt = generateChangesEntityScenariosGenerator({
     entity,
     mergedDataStructure: analysis.metadata.mergedDataStructure,
-    keyAttributes,
-    addedKeyAttributes,
-    removedKeyAttributes,
-    modifiedKeyAttributes,
-    dependentAnalyses,
+    executionFlows,
+    addedFlows,
+    removedFlows,
     existingScenarios,
     commitDiff,
     error,
@@ -101,7 +94,7 @@ export default async function generateChangesEntityScenarios({
     type: `generate${error ? 'Error' : ''}ChangesEntityScenarios`,
     systemMessage: error
       ? ERROR_SYSTEM_MESSAGE
-      : generateChangesSystemMessage(context, scenarioCount, false),
+      : generateChangesSystemMessage(context, scenarioCount),
     prompt,
     model: model ?? DEFAULT_LARGER_MODEL,
   });
@@ -119,32 +112,17 @@ export default async function generateChangesEntityScenarios({
           path: entity.file.path,
         },
       },
-      keyAttributes,
-      addedKeyAttributes,
-      removedKeyAttributes,
-      dependentAnalyses: Object.fromEntries(
-        Object.entries(dependentAnalyses ?? {}).map(([path, analyses]) => [
-          path,
-          Object.fromEntries(
-            Object.entries(analyses).map(([name, analysis]) => [
-              name,
-              {
-                metadata: {
-                  keyAttributes: analysis.metadata?.keyAttributes,
-                },
-              },
-            ]),
-          ),
-        ]),
-      ),
+      executionFlows,
+      addedFlows,
+      removedFlows,
       existingScenarios: existingScenarios.map((s) => ({
         id: s.id,
         name: s.name,
         description: s.description,
         metadata: {
-          error: s.metadata.error,
-          keyAttributeInstructions: s.metadata.keyAttributeInstructions,
-          playwrightInstructions: s.metadata.playwrightInstructions,
+          error: s.metadata?.error,
+          coveredFlows: s.metadata?.coveredFlows,
+          playwrightInstructions: s.metadata?.playwrightInstructions,
         },
       })),
       commitDiff,
@@ -154,7 +132,7 @@ export default async function generateChangesEntityScenarios({
           isolatedDataStructure: {
             equivalentSignatureVariables:
               entity.metadata.isolatedDataStructure
-                .equivalentSignatureVariables,
+                ?.equivalentSignatureVariables,
           },
         },
       },
@@ -199,7 +177,7 @@ export default async function generateChangesEntityScenarios({
     );
 
     const revisedFromPreviousVersion = previousVersion
-      ? !!scenarioInfo.keyAttributeInstructions
+      ? !!scenarioInfo.coveredFlows
       : undefined;
     const useScenarioData = !previousVersion || revisedFromPreviousVersion;
 
@@ -212,59 +190,42 @@ export default async function generateChangesEntityScenarios({
         : previousVersion.description,
       metadata: {
         testName:
-          useScenarioData || !previousVersion.metadata.testName
+          useScenarioData || !previousVersion?.metadata?.testName
             ? scenarioInfo.testName
             : previousVersion.metadata.testName,
         error,
         revisedFromPreviousVersion,
         codeSnippet: useScenarioData
           ? scenarioInfo.codeSnippet
-          : previousVersion.metadata.codeSnippet,
-        fix: useScenarioData ? scenarioInfo.fix : previousVersion.metadata.fix,
+          : previousVersion?.metadata?.codeSnippet,
+        fix: useScenarioData
+          ? scenarioInfo.fix
+          : previousVersion?.metadata?.fix,
         fixSnippet: useScenarioData
           ? scenarioInfo.fixSnippet
-          : previousVersion.metadata.fixSnippet,
+          : previousVersion?.metadata?.fixSnippet,
         likelihood: useScenarioData
           ? scenarioInfo.likelihood
-          : previousVersion.metadata.likelihood,
+          : previousVersion?.metadata?.likelihood,
         likelihoodDescription: useScenarioData
           ? scenarioInfo.likelihoodDescription
-          : previousVersion.metadata.likelihoodDescription,
+          : previousVersion?.metadata?.likelihoodDescription,
         severity: useScenarioData
           ? scenarioInfo.severity
-          : previousVersion.metadata.severity,
+          : previousVersion?.metadata?.severity,
         severityDescription: useScenarioData
           ? scenarioInfo.severityDescription
-          : previousVersion.metadata.severityDescription,
-        dataMapping: useScenarioData
-          ? scenarioInfo.dataMapping
-          : previousVersion.metadata.dataMapping,
-        keyAttributeInstructions: useScenarioData
-          ? Object.keys(scenarioInfo.keyAttributeInstructions).reduce(
-              (acc: any, key) => {
-                // LLM is instructed to use localVariable (internalPath) as key
-                const attributesList = keyAttributes.map(
-                  (attr) => attr.internalPath,
-                );
-                const matchingKey = findMatchingAttribute(
-                  key,
-                  attributesList,
-                  entity.metadata.isolatedDataStructure
-                    .equivalentSignatureVariables,
-                );
-                acc[matchingKey] = scenarioInfo.keyAttributeInstructions[key];
-                return acc;
-              },
-              {},
-            )
-          : previousVersion.metadata.keyAttributeInstructions,
+          : previousVersion?.metadata?.severityDescription,
+        coveredFlows: useScenarioData
+          ? scenarioInfo.coveredFlows || []
+          : previousVersion?.metadata?.coveredFlows || [],
         playwrightInstructions: useScenarioData
           ? sanitizePlaywrightInstructions(
               scenarioInfo.playwrightInstructions || [],
               entity.name,
               scenarioInfo.name,
             )
-          : previousVersion.metadata.playwrightInstructions,
+          : previousVersion?.metadata?.playwrightInstructions,
       },
       previousVersionId: previousVersion?.id,
     });
@@ -280,7 +241,6 @@ export default async function generateChangesEntityScenarios({
 function generateChangesSystemMessage(
   context?: string,
   scenarioCount?: number,
-  _isError?: boolean,
 ): string {
   const contextSection = context
     ? `## Business Context
@@ -297,55 +257,35 @@ Focus scenario updates on demonstrating this change.${scenarioCount ? ` Generate
 
   return `You are updating data scenarios after a code change. Determine which existing scenarios need updating, which should be removed, and if new ones are needed.
 
-${contextSection}## Coverage Goals (IMPORTANT)
-Your primary goal is to MAXIMIZE coverage of key attributes across all scenarios:
-
-1. **Use indexed validValueOptions**: Each key attribute has indexed \`validValueOptions\` (with \`index\` and \`value\`). Reference these by index in your valueOptionRef.
+${contextSection}## Your Goal: Maintain Full Execution Flow Coverage
 
-2. **Prioritize attributes with dependencies**: Key attributes with a \`dependencies\` array control conditionally-rendered content. Satisfy these dependencies to reveal gated UI/behavior.
+You are given:
+- \`executionFlows\`: All current distinct outcomes/behaviors this component can produce
+- \`addedFlows\`: New flows that didn't exist before
+- \`removedFlows\`: Flows that no longer exist
+- \`existingScenarios\`: Current scenarios with their coveredFlows
 
-3. **Cover conditional branches**: Use \`codeUsages\` to identify all conditional paths that need coverage.
+**Your job**: Update scenarios to maintain coverage of ALL current execution flows.
 
 ## Update Rules
 
-### Removed Key Attributes
-- Update scenarios using removed attributes—replace with new attributes or remove if no longer relevant
-- CRITICAL: "${DEFAULT_SCENARIO_NAME}" must NEVER contain removed attributes—update or replace them
-- Try to maintain 3+ scenarios; create replacements if removing too many
-
-### Added Key Attributes
-- Create or update scenarios to demonstrate new behavior
-- Use different validValueOption indices than existing scenarios to maximize coverage
+### Removed Flows
+- If an existing scenario only covers removed flows, remove the scenario
+- If a scenario covers both removed and current flows, update its coveredFlows to remove the deleted ones
 
-### Playwright Instructions
-- Validate existing instructions still work after code changes
-- Update any that reference changed UI elements
+### Added Flows
+- Create new scenarios or update existing ones to cover new flows
+- Follow the same rules as initial scenario generation:
+  - Blocking flows (blocksOtherFlows: true) get their own dedicated scenarios
+  - Non-blocking flows can be combined with compatible existing scenarios
 
 ### Unchanged Scenarios
-- Return name only (no other fields needed)
+- Return name only (no other fields needed) if the scenario's covered flows are all still valid
 
 ### Default Scenario
 - First scenario must be "${DEFAULT_SCENARIO_NAME}" (exact name)
 - NEVER include playwrightInstructions—captures initial state only
-- Must include all current key attributes with valid values from their validValueOptions
-
-## keyAttributeInstructions Format
-Use \`localVariable\` as key. Include instruction AND a valueOptionRef that references which validValueOption you're using:
-\`\`\`json
-{
-  "status": {
-    "instruction": "Set to 'active' mode",
-    "valueOptionRef": { "index": 0, "refType": "exact" }
-  }
-}
-\`\`\`
-
-### valueOptionRef Types
-- \`"exact"\`: Uses the validValueOption at this index exactly
-- \`"derived"\`: Based on this validValueOption but modified (include \`derivation\` field explaining how)
-- \`"custom"\`: Value not from validValueOptions list (use sparingly)
-
-The \`index\` refers to the validValueOptions array position (0 = first option).
+- Should cover as many non-blocking, non-error flows as possible
 
 ## Response Format
 
@@ -363,30 +303,31 @@ Otherwise:
   "overview": "Added empty state scenario for new display behavior.",
   "dataScenarios": [
     { "name": "${DEFAULT_SCENARIO_NAME}" },
-    { "name": "Many notifications" },
+    { "name": "Settings Modal" },
     {
-      "name": "No notifications",
-      "testName": "it(\\"shows empty message when no notifications\\")",
-      "description": "User has no notifications.",
-      "keyAttributeInstructions": {
-        "notifications[]": {
-          "instruction": "Empty array [] to show empty state",
-          "valueOptionRef": { "index": 1, "refType": "exact" }
-        }
-      }
+      "name": "Empty State",
+      "testName": "it(\\"shows empty message when no items\\")",
+      "description": "User has no items to display.",
+      "coveredFlows": ["empty-list"]
     }
   ]
 }
 \`\`\`
 
+## Field Descriptions
+
+- **name**: Human-readable scenario name (letters, numbers, spaces only)
+- **testName**: Jest-style test description (only for new/updated scenarios)
+- **description**: What the user sees (only for new/updated scenarios)
+- **coveredFlows**: Array of execution flow IDs this scenario covers (only for new/updated scenarios)
+- **playwrightInstructions**: User interactions needed (only for new/updated scenarios that require interaction)
+
 ## Rules
 - Scenario names: letters, numbers, spaces only
 - testName: Jest style with specific expectations
-- Use values from \`validValueOptions\` in key attributes list (reference by index)
-- Include dependency key attributes if dependencies involved
-- React elements: simple only (\`<div>\`, \`<span>\`)
-- No external library references—plain JS/TS values
-- Relative dates OK: "today", "tomorrow", "last month"
+- All values must be valid JSON
+- EVERY execution flow must be covered by at least one scenario
+- Blocking flows get dedicated scenarios
 `;
 }
 
@@ -421,27 +362,23 @@ Be conservative with high scores.
 - No external library references—mock with plain JS
 - Each scenario causes a DISTINCT error type
 
-Note: In JS/TS, any non-zero value satisfies a boolean check—this won't error.
-
 ## Response Format
 \`\`\`json
 {
   "errorDataScenarios": [
     { "name": "Existing valid error" },
     {
-      "dataMapping": { "notifications array": "props.notifications" },
       "name": "Non-utf8 encoding error",
-      "codeSnippet": "const encoded = encodeURIComponent(message);",
+      "testName": "it(\\"throws on non-utf8 characters\\")",
       "description": "encodeURIComponent throws on non-utf8 characters",
+      "codeSnippet": "const encoded = encodeURIComponent(message);",
       "fix": "Wrap in try/catch",
       "fixSnippet": "try { encoded = encodeURIComponent(message); } catch (e) { ... }",
       "likelihood": 7,
       "likelihoodDescription": "International users may input non-utf8 characters",
       "severity": 2,
       "severityDescription": "Function throws uncaught error",
-      "keyAttributeInstructions": {
-        "notifications[]": "Array with message containing non-utf8 characters"
-      }
+      "coveredFlows": []
     }
   ]
 }

package/analyzer-template/packages/ai/src/lib/generateEntityDataStructure.ts

@@ -1,9 +1,12 @@
 import { Entity } from '~codeyam/types';
 import isolateScopes from './isolateScopes';
 import analyzeScope from './analyzeScope';
-import { FileAnalyzer } from '~codeyam/analyze';
+import { FileAnalyzer, transformationTracer } from '~codeyam/analyze';
 import { AI, SerializableDataStructure } from '~codeyam/ai';
-import { resetScopeDataStructureMetrics } from './dataStructure/ScopeDataStructure';
+import {
+  resetScopeDataStructureMetrics,
+  ScopeDataStructure,
+} from './dataStructure/ScopeDataStructure';
 
 // import { awsLog } from '~codeyam/utils';
 
@@ -33,6 +36,7 @@ export default async function generateEntityDataStructure({
   const fileText = fileAnalyzer.sourceFile.getFullText();
   const fileScope = isolateScopes(fileText, {
     entityNames: [entity.name],
+    jsxLimit: 10, // Enable gating condition extraction for child component flow merging
   });
 
   let entityScope =
@@ -90,8 +94,60 @@ export default async function generateEntityDataStructure({
   }
 
   // Inspect the runtime type of dataStructure to see if it must be serialized
+  // Note: When worker threads are used, dataStructure is already serialized (no toSerializable).
+  // Workers are disabled when CODEYAM_TRACE_TRANSFORMS=1 to enable full tracing.
   if ('toSerializable' in entityScope.dataStructure) {
-    return entityScope.dataStructure.toSerializable();
+    const scopeDataStructure =
+      entityScope.dataStructure as unknown as ScopeDataStructure;
+
+    // Trace the internal state BEFORE serialization - captures what methods return
+    if (transformationTracer.isEnabled()) {
+      transformationTracer.startEntity({
+        name: entity.name,
+        entityType: entity.entityType ?? 'unknown',
+        filePath: entity.filePath,
+      });
+
+      // Capture internal state - this is what getReturnValue/getFunctionSignature return
+      transformationTracer.snapshot(entity.name, 'scopeDataStructure', {
+        signatureSchema: scopeDataStructure.getFunctionSignature({
+          fillInUnknowns: true,
+        }),
+        returnValueSchema: scopeDataStructure.getReturnValue({
+          fillInUnknowns: true,
+        }),
+      });
+    }
+
+    const serialized = scopeDataStructure.toSerializable();
+
+    // Trace AFTER serialization - shows what gets output
+    if (transformationTracer.isEnabled()) {
+      // Build schema from external function calls for comparison
+      const externalSchemas: Record<string, string> = {};
+      for (const efc of serialized.externalFunctionCalls ?? []) {
+        for (const [path, type] of Object.entries(efc.schema ?? {})) {
+          externalSchemas[path] = type;
+        }
+      }
+
+      transformationTracer.snapshot(entity.name, 'serialized', {
+        signatureSchema:
+          serialized.functionResults?.[entity.name]?.signatureWithUnknowns,
+        returnValueSchema:
+          serialized.functionResults?.[entity.name]?.returnValueWithUnknowns,
+        // Include external function schemas to detect serialization gaps
+        dependencySchemas: {
+          externalFunctions: {
+            combined: {
+              returnValueSchema: externalSchemas,
+            },
+          },
+        },
+      });
+    }
+
+    return serialized;
   }
   return entityScope.dataStructure;
 }