subgraph model & validation

src/wf_core/runtime/ops/foreach.py

@@ -340,6 +340,8 @@ def _finish_concurrent_foreach(
             raise WorkflowExecutionError(
                 "collect item error policy requires collect_to"
             )
+        # Collect-error records are generated by the barrier itself, not by an
+        # item lineage, so they still enter as a compatibility `changes` patch.
         item_patches.append(StatePatch(changes={str(collect_to): error_records}))
     combined = build_barrier_patch(
         workflow,

src/wf_core/runtime/ops/nodes.py

@@ -124,6 +124,8 @@ def _finalize_node_execution(
         if is_root_lineage_frame(frame):
             state_changes = commit_state_patch(run.state, patch)
         else:
+            # Non-root frames are future subgraph/fork branch execution: writes
+            # become lineage-local until an explicit boundary/barrier commits.
             append_lineage_writes(
                 run,
                 scope_id=frame.scope_id,
@@ -136,6 +138,8 @@ def _finalize_node_execution(
         parent_frame = run.frames[parent_frame_id]
         barrier = ForeachBarrierState.from_frame(parent_frame, foreach_node_id)
         if barrier is not None and barrier.mode == "concurrent":
+            # New concurrent foreach stores writes in the child lineage; the
+            # barrier keeps only result metadata plus old patch fallback.
             append_lineage_writes(
                 run,
                 scope_id=frame.scope_id,

src/wf_core/runtime/ops/state.py

@@ -49,7 +49,12 @@ class StatePatch:
     _staged_state: dict[str, Any] = dataclass_field(default_factory=dict, repr=False)
 
     def __post_init__(self) -> None:
-        """Keep legacy `StatePatch(changes=...)` usable during migration."""
+        """Keep legacy `StatePatch(changes=...)` usable during migration.
+
+        New runtime code should prefer ordered `writes`. `changes` stays as the
+        public trace-facing view and as parse compatibility for old barrier
+        metadata/tests that predate `StateWrite`.
+        """
         if not self.changes and self.writes:
             self.changes = {
                 str(write.path): write.incoming_value for write in self.writes