singledigit
diff --git a/‎docs/cfn-language-extensions.md‎
Lines changed: 125 additions & 1 deletion b/‎docs/cfn-language-extensions.md‎
Lines changed: 125 additions & 1 deletion
diff --git a/‎samcli/commands/_utils/template.py‎
Lines changed: 10 additions & 1 deletion b/‎samcli/commands/_utils/template.py‎
Lines changed: 10 additions & 1 deletion
diff --git a/‎samcli/commands/build/build_context.py‎
Lines changed: 60 additions & 16 deletions b/‎samcli/commands/build/build_context.py‎
Lines changed: 60 additions & 16 deletions
@@ -41,7 +41,37 @@ Running `sam build` expands this into `UsersFunction`, `OrdersFunction`, and `Pr
 
 ### Dynamic artifact properties
 
-When a packageable property (like `CodeUri`, `ContentUri`, `ImageUri`) uses a loop variable (e.g., `./services/${Name}`), SAM CLI generates a CloudFormation `Mappings` section that maps each collection value to its S3 URI. The `Fn::ForEach` body is rewritten to use `Fn::FindInMap` so CloudFormation can resolve the correct artifact at deploy time.
+When a packageable property uses a loop variable (e.g., `./services/${Name}`), SAM CLI generates a CloudFormation `Mappings` section that maps each collection value to its S3 URI. The `Fn::ForEach` body is rewritten to use `Fn::FindInMap` so CloudFormation can resolve the correct artifact at deploy time.
+
+The set of recognized artifact properties is derived from the same canonical list `sam package` already uses (`RESOURCES_WITH_LOCAL_PATHS` and `RESOURCES_WITH_IMAGE_COMPONENT` in `samcli/lib/utils/resources.py`), so every resource type whose artifact property `sam package` would normally rewrite is supported here too. That includes:
+
+| Resource type | Property |
+|---------------|----------|
+| `AWS::Serverless::Function` | `CodeUri`, `ImageUri` |
+| `AWS::Serverless::LayerVersion` | `ContentUri` |
+| `AWS::Serverless::Api` | `DefinitionUri` |
+| `AWS::Serverless::HttpApi` | `DefinitionUri` |
+| `AWS::Serverless::StateMachine` | `DefinitionUri` |
+| `AWS::Serverless::GraphQLApi` | `SchemaUri`, `CodeUri` |
+| `AWS::Serverless::Application` | `Location` |
+| `AWS::Lambda::Function` | `Code`, `Code.ImageUri` |
+| `AWS::Lambda::LayerVersion` | `Content` |
+| `AWS::ApiGateway::RestApi` | `BodyS3Location` |
+| `AWS::ApiGatewayV2::Api` | `BodyS3Location` |
+| `AWS::AppSync::GraphQLSchema` | `DefinitionS3Location` |
+| `AWS::AppSync::Resolver` | `RequestMappingTemplateS3Location`, `ResponseMappingTemplateS3Location`, `CodeS3Location` |
+| `AWS::AppSync::FunctionConfiguration` | `RequestMappingTemplateS3Location`, `ResponseMappingTemplateS3Location`, `CodeS3Location` |
+| `AWS::StepFunctions::StateMachine` | `DefinitionS3Location` |
+| `AWS::ElasticBeanstalk::ApplicationVersion` | `SourceBundle` |
+| `AWS::Glue::Job` | `Command.ScriptLocation` |
+| `AWS::CloudFormation::Stack` | `TemplateURL` |
+| `AWS::CloudFormation::StackSet` | `TemplateURL` |
+| `AWS::CloudFormation::ModuleVersion` | `ModulePackage` |
+| `AWS::CloudFormation::ResourceVersion` | `SchemaHandlerPackage` |
+
+When a property is dotted (e.g. `Command.ScriptLocation` on `AWS::Glue::Job` or `Code.ImageUri` on `AWS::Lambda::Function`), SAM CLI reads and writes the value at the dotted location on the resource — so it lands at `Properties.Command.ScriptLocation` rather than at a literal `Properties["Command.ScriptLocation"]` key — and uses only the leaf segment when it needs to construct an alphanumeric identifier (Mapping name suffix or `Fn::FindInMap` third argument).
+
+When the property is loop-templated, the Mapping name is `SAM<LeafProperty><LoopName>` (e.g., `SAMCodeUriServices`, `SAMScriptLocationJobs`). Customer-authored mappings should not start with these `SAM*` prefixes — they are reserved for SAM CLI (see [Limitations](#limitations) below).
 
 For example, after `sam package`:
 
@@ -67,6 +97,45 @@ Resources:
           CodeUri: !FindInMap [SAMCodeUriServices, !Ref Name, CodeUri]
 ```
 
+### Multiple resources per ForEach body
+
+A single `Fn::ForEach` body can emit more than one resource per iteration. Each resource is generated for every collection value:
+
+```yaml
+Resources:
+  Fn::ForEach::Tables:
+    - TableName
+    - [Users, Orders, Products]
+    - ${TableName}Table:
+        Type: AWS::DynamoDB::Table
+        Properties:
+          TableName: !Sub "${AWS::StackName}-${TableName}"
+          # ...
+
+      ${TableName}StreamProcessor:
+        Type: AWS::Serverless::Function
+        Properties:
+          CodeUri: stream-processors/${TableName}/
+          Events:
+            DDBStream:
+              Type: DynamoDB
+              Properties:
+                Stream: !GetAtt
+                  - !Sub "${TableName}Table"
+                  - StreamArn
+```
+
+### Mapping name collision resolution
+
+When two resources in the same `Fn::ForEach` body declare the same dynamic artifact property (for example, both an `Api` and a `StateMachine` use `DefinitionUri`), SAM CLI appends a sanitized suffix derived from the resource logical-ID template to keep Mapping names unique:
+
+| Resource template | Property | Mapping name |
+|-------------------|----------|--------------|
+| `${Svc}Api` | `DefinitionUri` | `SAMDefinitionUriServicesApi` |
+| `${Svc}StateMachine` | `DefinitionUri` | `SAMDefinitionUriServicesStateMachine` |
+
+When there is no collision the base name (e.g., `SAMDefinitionUriServices`) is used.
+
 ### Parameter-based collections
 
 When the `Fn::ForEach` collection is a parameter reference (`!Ref ServiceNames`), the collection values are resolved at package time from:
@@ -120,6 +189,46 @@ Resources:
                   STAGE: !Ref Env
 ```
 
+### ForEach in Outputs
+
+`Fn::ForEach` blocks are also expanded inside the `Outputs` section, so you can emit one output per collection value:
+
+```yaml
+Outputs:
+  Fn::ForEach::FunctionArns:
+    - Name
+    - [alpha, beta]
+    - ${Name}FunctionArn:
+        Value: !GetAtt
+          - !Sub "${Name}Function"
+          - Arn
+```
+
+### Conditions and DependsOn
+
+Resources emitted by `Fn::ForEach` can carry `Condition` and `DependsOn` like any other resource. The condition or dependency is replicated onto each generated resource:
+
+```yaml
+Conditions:
+  IsProd: !Equals [!Ref Environment, prod]
+
+Resources:
+  SharedTable:
+    Type: AWS::DynamoDB::Table
+    # ...
+
+  Fn::ForEach::Functions:
+    - Name
+    - [api, worker]
+    - ${Name}Function:
+        Type: AWS::Serverless::Function
+        Condition: IsProd
+        DependsOn: SharedTable
+        Properties:
+          Handler: main.handler
+          CodeUri: functions/${Name}/
+```
+
 ### &{identifier} syntax
 
 The `&{identifier}` syntax strips non-alphanumeric characters from the substituted value, useful for generating valid logical IDs from values like IP addresses:
@@ -154,11 +263,26 @@ The following intrinsic functions are resolved locally during expansion:
 
 Functions that require deployed resources (`Fn::GetAtt`, `Fn::ImportValue`, `Fn::GetAZs`) are preserved for CloudFormation to resolve at deploy time.
 
+## Validation errors
+
+The following template issues are caught locally before the SAM transform runs:
+
+| Cause | Error message |
+|-------|---------------|
+| The `Fn::ForEach` value is malformed — not a list, doesn't have exactly 3 elements, or has a non-string loop identifier. | `Fn::ForEach::<key> layout is incorrect` (raised as `InvalidTemplateException`; see `samcli/lib/cfn_language_extensions/processors/foreach.py`). |
+| More than 5 levels of `Fn::ForEach` are nested. | `Fn::ForEach nesting depth of <N> exceeds the maximum allowed depth of 5. CloudFormation supports up to 5 nested Fn::ForEach loops.` |
+| The collection resolves to an empty list (e.g., a `CommaDelimitedList` parameter with `Default: ""`). | No error — the loop is silently skipped and no resources are emitted. |
+| The `!Ref` in the collection points at a parameter that is not declared in the template. | No error in the typical `sam build` / `sam package` flow. SAM CLI runs intrinsic resolution in PARTIAL mode and preserves the unresolved `{"Ref": "<name>"}`. CloudFormation will reject the unresolved ref at deploy time. |
+
 ## Limitations
 
 - **Collections must be resolvable at build/package time.** `Fn::ForEach` collections that use `Fn::GetAtt`, `Fn::ImportValue`, or SSM/Secrets Manager dynamic references cannot be expanded locally. Use a parameter with `--parameter-overrides` instead.
 - **Parameter values are fixed at package time.** If you change `--parameter-overrides` at deploy time without re-packaging, the Mappings won't include entries for new values and deployment will fail.
 - **`DeletionPolicy` and `UpdateReplacePolicy`** are validated and resolved during expansion. They support `Ref` to parameters but not other intrinsic functions.
+- **Nesting limit.** Up to 5 levels of `Fn::ForEach` may be nested, matching CloudFormation's server-side limit.
+- **Reserved Mapping names.** Mapping names starting with any of the following are reserved for SAM CLI — do not author your own mappings with these prefixes:
+  - `SAMCodeUri`, `SAMImageUri`, `SAMContentUri`, `SAMDefinitionUri`, `SAMSchemaUri`, `SAMBodyS3Location`, `SAMDefinitionS3Location`, `SAMTemplateURL`, `SAMCode`, `SAMContent` — emitted by `sam package` for dynamic artifact properties (see the table above).
+  - `SAMLayers` — emitted by `sam build` when a `Fn::ForEach`-generated function picks up auto-generated dependency-layer references (Lambda layers SAM CLI builds into a nested stack). This prefix has no corresponding user-authored property; it is added automatically.
 
 ## Telemetry
 
 
@@ -33,8 +33,17 @@
 # Artifact path property names derived from PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES
 # so the two lists cannot drift. Used by _update_sam_mappings_relative_paths to
 # identify which SAM-generated Mapping values are local paths needing adjustment.
+#
+# Includes both the dotted form (e.g. "Command.ScriptLocation") and its leaf
+# (e.g. "ScriptLocation"), because SAM-generated Mapping value-dicts are keyed
+# by the leaf segment so the third argument of Fn::FindInMap stays alphanumeric
+# (see _compute_mapping_name and _generate_artifact_mappings in
+# samcli/lib/package/language_extensions_packaging.py).
 _ARTIFACT_PATH_PROPERTIES = frozenset(
-    prop for props in PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES.values() for prop in props
+    name
+    for props in PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES.values()
+    for prop in props
+    for name in (prop, prop.rsplit(".", 1)[-1])
 )
 
 
 
@@ -553,6 +553,12 @@ def _update_foreach_artifact_paths(
         """
         from samcli.lib.cfn_language_extensions.models import PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES
         from samcli.lib.cfn_language_extensions.sam_integration import resolve_collection
+        from samcli.lib.package.language_extensions_packaging import (
+            _get_prop_value,
+            _leaf_prop_name,
+            _resolve_property_paths,
+            _set_prop_value,
+        )
 
         generated_mappings: Dict[str, Dict[str, Dict[str, str]]] = {}
 
@@ -599,11 +605,17 @@ def _update_foreach_artifact_paths(
             if not isinstance(properties, dict):
                 continue
 
-            for prop_name in PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES.get(resource_type, []):
-                prop_value = properties.get(prop_name)
+            candidate_paths = PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES.get(resource_type, [])
+            for prop_name in _resolve_property_paths(candidate_paths, properties):
+                prop_value = _get_prop_value(properties, prop_name)
                 if prop_value is None:
                     continue
 
+                # CloudFormation Mapping names and FindInMap third-args must be alphanumeric,
+                # so dotted property names (e.g. "Command.ScriptLocation") use the leaf segment
+                # for those identifiers while the dotted form is preserved for property addressing.
+                leaf_name = _leaf_prop_name(prop_name)
+
                 if contains_loop_variable(prop_value, loop_variable) and collection_values:
                     # Determine which outer loop variables the property references
                     referenced_outer_vars = []
@@ -622,8 +634,12 @@ def _update_foreach_artifact_paths(
                         referenced_outer_vars=referenced_outer_vars,
                     )
                     if mapping_entries:
-                        mapping_name = f"SAM{prop_name}{nesting_path}"
-                        if dynamic_props_count.get(prop_name, 0) > 1:
+                        mapping_name = f"SAM{leaf_name}{nesting_path}"
+                        # Collision count is keyed on the leaf so dotted paths
+                        # that share a leaf (e.g. "ImageUri" vs "Code.ImageUri")
+                        # get the resource-key suffix and don't overwrite each
+                        # other's Mapping entries.
+                        if dynamic_props_count.get(leaf_name, 0) > 1:
                             suffix = sanitize_resource_key_for_mapping(resource_template_key)
                             mapping_name = f"{mapping_name}{suffix}"
                         generated_mappings[mapping_name] = mapping_entries
@@ -637,7 +653,7 @@ def _update_foreach_artifact_paths(
                         else:
                             lookup_key = {"Ref": loop_variable}
 
-                        properties[prop_name] = {"Fn::FindInMap": [mapping_name, lookup_key, prop_name]}
+                        _set_prop_value(properties, prop_name, {"Fn::FindInMap": [mapping_name, lookup_key, leaf_name]})
                 else:
                     expanded_key = self._build_expanded_key(
                         resource_template_key,
@@ -648,7 +664,7 @@ def _update_foreach_artifact_paths(
                     if expanded_key:
                         artifact_value = self._get_artifact_value(modified_resources, expanded_key, prop_name)
                         if artifact_value is not None:
-                            properties[prop_name] = artifact_value
+                            _set_prop_value(properties, prop_name, artifact_value)
 
             # Propagate auto dependency layer references from expanded functions
             # to the ForEach body. Each expanded function may have Layers entries
@@ -707,6 +723,11 @@ def _count_dynamic_properties(
         share the same property name (e.g., two resources both with DefinitionUri).
         """
         from samcli.lib.cfn_language_extensions.models import PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES
+        from samcli.lib.package.language_extensions_packaging import (
+            _get_prop_value,
+            _leaf_prop_name,
+            _resolve_property_paths,
+        )
 
         count: Counter = Counter()
         for rtk, rt in body.items():
@@ -718,10 +739,13 @@ def _count_dynamic_properties(
             rprops = rt.get("Properties", {})
             if not isinstance(rprops, dict):
                 continue
-            for pname in PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES.get(rtype, []):
-                pval = rprops.get(pname)
+            candidate_paths = PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES.get(rtype, [])
+            for pname in _resolve_property_paths(candidate_paths, rprops):
+                pval = _get_prop_value(rprops, pname)
                 if pval is not None and contains_loop_variable(pval, loop_variable) and collection_values:
-                    count[pname] += 1
+                    # Count by leaf so collisions across resource types with
+                    # different dotted paths but the same leaf are detected.
+                    count[_leaf_prop_name(pname)] += 1
         return count
 
     @staticmethod
@@ -759,8 +783,15 @@ def _collect_dynamic_mapping_entries(
 
         For nested ForEach, enumerates all outer value combinations to find
         the fully-expanded resource name.
+
+        ``prop_name`` may be a jmespath dotted path; the value-dict key stored
+        in the Mapping uses the leaf segment so it stays alphanumeric and
+        matches the third argument of the generated Fn::FindInMap.
         """
+        from samcli.lib.package.language_extensions_packaging import _leaf_prop_name
+
         mapping_entries: Dict[str, Dict[str, str]] = {}
+        leaf_name = _leaf_prop_name(prop_name)
 
         for coll_value in collection_values:
             if outer_context:
@@ -778,7 +809,7 @@ def _collect_dynamic_mapping_entries(
                 expanded_key = substitute_loop_variable(resource_template_key, loop_variable, coll_value)
                 artifact_value = self._get_artifact_value(modified_resources, expanded_key, prop_name)
                 if artifact_value is not None:
-                    mapping_entries[coll_value] = {prop_name: artifact_value}
+                    mapping_entries[coll_value] = {leaf_name: artifact_value}
 
         return mapping_entries
 
@@ -793,9 +824,15 @@ def _collect_nested_mapping_entry(
         mapping_entries: Dict[str, Dict[str, str]],
         referenced_outer_vars: Optional[List[Tuple[str, List[str]]]] = None,
     ) -> None:
-        """Enumerate outer value combinations to find expanded resource for a nested ForEach."""
+        """Enumerate outer value combinations to find expanded resource for a nested ForEach.
+
+        ``prop_name`` may be a jmespath dotted path; the value-dict key uses the leaf segment.
+        """
         import itertools
 
+        from samcli.lib.package.language_extensions_packaging import _leaf_prop_name
+
+        leaf_name = _leaf_prop_name(prop_name)
         outer_collections = [oc[1] for oc in outer_context]
         outer_vars = [oc[0] for oc in outer_context]
 
@@ -821,7 +858,7 @@ def _collect_nested_mapping_entry(
                 mapping_key = coll_value
 
             if mapping_key not in mapping_entries:
-                mapping_entries[mapping_key] = {prop_name: artifact_value}
+                mapping_entries[mapping_key] = {leaf_name: artifact_value}
 
     def _collect_foreach_layer_mappings(
         self,
@@ -895,14 +932,19 @@ def _extract_nested_stack_layer_output(modified_resources: Dict, expanded_key: s
 
     @staticmethod
     def _get_artifact_value(modified_resources: Dict, expanded_key: str, prop_name: str) -> Optional[Any]:
-        """Extract an artifact property value from an expanded resource, or return None."""
+        """Extract an artifact property value from an expanded resource, or return None.
+
+        ``prop_name`` may be a jmespath dotted path (e.g. "Command.ScriptLocation").
+        """
+        from samcli.lib.package.language_extensions_packaging import _get_prop_value
+
         modified_resource = modified_resources.get(expanded_key, {})
         if not isinstance(modified_resource, dict):
             return None
         modified_props = modified_resource.get("Properties", {})
         if not isinstance(modified_props, dict):
             return None
-        return modified_props.get(prop_name)
+        return _get_prop_value(modified_props, prop_name)
 
     def _copy_artifact_paths(self, original_resource: Dict, modified_resource: Dict) -> None:
         """
@@ -919,6 +961,7 @@ def _copy_artifact_paths(self, original_resource: Dict, modified_resource: Dict)
             The modified resource with updated artifact paths
         """
         from samcli.lib.cfn_language_extensions.models import PACKAGEABLE_RESOURCE_ARTIFACT_PROPERTIES
+        from samcli.lib.package.language_extensions_packaging import _get_prop_value, _set_prop_value
 
         original_props = original_resource.get("Properties", {})
         modified_props = modified_resource.get("Properties", {})
@@ -929,8 +972,9 @@ def _copy_artifact_paths(self, original_resource: Dict, modified_resource: Dict)
             return
 
         for prop_name in prop_names:
-            if prop_name in modified_props:
-                original_props[prop_name] = modified_props[prop_name]
+            value = _get_prop_value(modified_props, prop_name)
+            if value is not None:
+                _set_prop_value(original_props, prop_name, value)
 
     def _gen_success_msg(self, artifacts_dir: str, output_template_path: str, is_default_build_dir: bool) -> str:
         """