Document what rc.10-57 changed about foreach, and fix what it caught

Three changes, all verified by compiling rather than read off the commits.

`foreach` now binds its element over the loop body, so the natural example
comes back OUT of the precise skip it was parked under and is gated again.
The control matters more than the fix: `line.nosuch` is still an Error, so
the binding carries the element's TYPE and did not become a hole admitting
any member.

`foreach` also iterates any resolvable collection, which answers the ruling
this repo asked for — the dotted `order.lines` was not a deliberate
restriction. The wrapper's iterable therefore moves back onto `order`,
where an author would put it, instead of being hoisted to a direct field of
the state to satisfy the old rule.

`foreach k, v` destructuring is new and documented in both the concepts
page and the reference, with the arity errors tabulated in both directions
— one name over a mapping, two over anything else. Each documented example
was compiled before prose was written around it.

Caught by the upgrade: `type.md`'s `mapping from Pattern(...) to
DictionaryEntry` named a type that does not exist. It passed only because a
mapping's VALUE type was never resolved; rc.10-57 resolves it. Same shape
as the interaction-group fix — a resolver gap closing turns a silent pass
into a real failure, and the example was wrong all along.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: reid-spencer

scripts/validate-riddl-examples.py

@@ -314,13 +314,14 @@ def ind(txt: str, n: int) -> str:
             "    record ExampleOrder is { id is String, number is String,\n"
             "      total is Natural, status is String, isPaid is Boolean,\n"
             "      isCancelled is Boolean, isRefunded is Boolean,\n"
-            "      confirmationNumber is String, items is many ExampleLine }\n"
-            # The state record: `foreach ... in field X` takes a DIRECT field of
-            # the state, handled message or function input -- a dotted path such
-            # as `order.lines` is rejected -- so the iterable lives here.
+            "      confirmationNumber is String, items is many ExampleLine,\n"
+            "      lines is many ExampleLine,\n"
+            "      prices is mapping from String to ExampleLine }\n"
+            # `foreach` resolves any path that lands on a collection (rc.10-57),
+            # so the iterable sits where an author would put it -- on `order` --
+            # rather than being hoisted to a direct field of the state.
             "    record ExampleData is { note is String, itemCount is Natural,\n"
-            "      id is String, total is Natural, balance is Natural,\n"
-            "      lines is many ExampleLine }\n"
+            "      id is String, total is Natural, balance is Natural }\n"
             "    command ExampleCommand is { note is String, cart is ExampleData,\n"
             "      order is ExampleOrder, orderId is String, amount is Natural,\n"
             "      limits is ExampleLimit }\n"

sites/riddl/docs/concepts/statement.md

@@ -217,7 +217,7 @@ Alternation — a non-exhaustive match without `default` draws a
 RIDDL's only loop, and deliberately bounded — there is no unbounded iteration
 in the language:
 
-<!-- riddl: skip reason="riddlc rc.10-46 does not put the loop variable in scope; see riddl task 2026-08-09-foreach-loop-variable-not-in-scope" -->
+<!-- riddl: in-handler -->
 ```riddl
 foreach line in field order.lines {
   send event LineShipped(sku = line.sku) to outlet Shipments
@@ -226,7 +226,31 @@ foreach line in field order.lines {
 
 The collection is a `field` reference or a `let`-bound local whose type
 resolves to a collection: Sequence, Set, Graph, Table, Replica, Mapping, or a
-cardinality wrapper such as `many` or `optional`.
+cardinality wrapper such as `many` or `optional`. Any path that lands on a
+collection will do — the field need not be a direct field of the state, as
+`order.lines` above shows.
+
+**The element is bound over the loop body**, and it carries the element's
+*type*, not merely its name: `line.sku` resolves, while `line.nosuch` is an
+Error. The binding ends at the closing brace, so referring to it after the
+loop is an Error too.
+
+#### Destructuring a mapping
+
+A mapping has two halves, so iterating one binds **two** names — a key and a
+value:
+
+<!-- riddl: in-handler -->
+```riddl
+foreach sku, price in field order.prices {
+  send event LineShipped(sku = sku) to outlet Shipments
+}
+```
+
+The arity is checked both ways, and each mistake has its own message:
+
+- one name over a mapping — *"binds a key AND a value, so it needs two names"*
+- two names over anything else — *"binds a second name only over a mapping"*
 
 ### Send, Tell, Yield and Reply
 

sites/riddl/docs/concepts/type.md

@@ -150,7 +150,13 @@ A type can be defined as a mapping from one type (the key) to another type
 (the value). For example, here is a dictionary definition that maps a word
 (lower case letters) to a type named DictionaryEntry that presumably
 contains all the things one would find in a dictionary entry.
-<!-- riddl: in-domain -->
+<!-- riddl-prelude
+record DictionaryEntry is {
+  headword is String
+  definition is String
+}
+-->
+<!-- riddl: in-context -->
 ```riddl
 type dictionary = mapping from Pattern("[a-z]+") to DictionaryEntry
 ```

sites/riddl/docs/references/language-reference.md

@@ -1422,7 +1422,32 @@ foreach item in myLocalCollection {
 
 The collection is a `field` reference or a `let`-bound local whose type resolves
 to a collection — Sequence, Set, Graph, Table, Replica, Mapping, or a
-cardinality wrapper such as `many` or `optional`.
+cardinality wrapper such as `many` or `optional`. **Any resolvable path that
+lands on a collection is accepted**; it need not be a direct field of the
+enclosing state, which is why `order.lines` above works.
+
+The element name is **bound over the loop body** and carries the element's
+type, so `line.sku` resolves and `line.nosuch` is an Error. The binding ends at
+the closing brace.
+
+#### Destructuring a mapping
+
+A mapping yields a key and a value, so iterating one binds **two** names:
+
+<!-- riddl: in-handler -->
+```riddl
+foreach sku, price in field order.prices {
+  send event LineShipped(sku = sku) to outlet Shipments
+}
+```
+
+Arity is a validation rule rather than a grammatical one — both shapes parse —
+and it is checked in both directions:
+
+| Mistake | Message |
+|---|---|
+| one name over a mapping | *binds a key AND a value, so it needs two names* |
+| two names over a non-mapping | *binds a second name only over a mapping* |
 
 ### Require Statement