feat: preserve change object refresh modifier

Mendix change-object actions can have RefreshInClient=true even when they also change members, but MDL had no syntax for that flag. Describing and rebuilding such an action therefore rewrote the flag to false.

The grammar now accepts an optional `refresh` modifier on change-object statements, the AST carries that flag, the formatter emits it for refreshed change actions, and the builder writes it back to ChangeObjectAction.RefreshInClient.

Tests cover parser, formatter, and builder behavior with and without member assignments. The branch also adds a draft proposal, doctype fixture, quick-reference entry, and skill guidance; `mxcli check` on the fixture plus make build, make lint-go, and make test pass locally.

Author: hjothamendix

.claude/skills/mendix/write-microflows.md

@@ -378,6 +378,9 @@ $NewProduct = create Test.Product (
 change $Product (
   Name = $NewName,
   ModifiedDate = [%CurrentDateTime%]);
+
+-- Refresh the changed object in the client
+change $Product (Name = $NewName) refresh;
 ```
 
 **Note**: Only specify attributes you want to change. Syntax aligned with CREATE.

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -218,7 +218,7 @@ authentication basic, session
 | List declaration | `declare $list list of Module.Entity = empty;` | |
 | Assignment | `set $Var = expression;` | Variable must be declared first |
 | Create object | `$Var = create Module.Entity (attr = value);` | |
-| Change object | `change $entity (attr = value);` | |
+| Change object | `change $entity (attr = value) [refresh];` | `refresh` updates the changed object in the client |
 | Commit | `commit $entity [with events] [refresh];` | |
 | Delete | `delete $entity;` | |
 | Rollback | `rollback $entity [refresh];` | Reverts uncommitted changes |

docs/11-proposals/PROPOSAL_microflow_change_refresh_modifier.md

@@ -0,0 +1,28 @@
+# Proposal: Microflow CHANGE Refresh Modifier
+
+Status: Draft
+
+## Summary
+
+Allow `change` microflow statements to explicitly preserve the Mendix `RefreshInClient` flag:
+
+```mdl
+change $Customer (Name = 'Jane') refresh;
+change $Customer refresh;
+```
+
+## Motivation
+
+Mendix change-object actions can refresh the changed object in the client independently from committing the object. MDL previously had no syntax for that flag, so a describe/exec round-trip could rewrite `RefreshInClient = true` to `false` for change actions with member assignments.
+
+## Semantics
+
+The `refresh` modifier maps directly to `ChangeObjectAction.RefreshInClient`. Omitting it preserves the existing default behavior. The modifier is accepted both with member assignments and on a memberless change action.
+
+## Tests And Examples
+
+`mdl-examples/doctype-tests/change_refresh_modifier.test.mdl` demonstrates both forms. Go tests cover formatter output, parser behavior, and builder serialization.
+
+## Open Questions
+
+- Should a memberless `change $Object;` continue to infer refresh in separate validity-focused fixes, or should the explicit `refresh` modifier be the only authoring form?

docs/11-proposals/README.md

@@ -49,6 +49,7 @@ BSON schema Registry ◄──── multi-version Support
 | [Page Styling Support](page-styling-support.md) | Partial | CSS classes, inline styles, dynamic classes, design properties. Phase 1 (Class/Style) done | — |
 | [Page Composition](proposal_page_composition.md) | Proposed | Fragment definitions and ALTER PAGE for partial page editing | Page Syntax V2, Page Styling |
 | [XPath Gaps](xpath-gaps-proposal.md) | Partial | XPath constraint support gap analysis. ~85% complete, association paths and nested predicates remain | — |
+| [Microflow CHANGE Refresh Modifier](PROPOSAL_microflow_change_refresh_modifier.md) | Draft | Preserve `RefreshInClient` on change-object actions | — |
 | [LLM MDL Assistance](PROPOSAL_llm_mdl_assistance.md) | Proposed | Enhanced error messages with examples, reorganized skills by use case | — |
 
 ### Testing & Evaluation

mdl-examples/doctype-tests/change_refresh_modifier.test.mdl

@@ -0,0 +1,17 @@
+create module ChangeRefreshExample;
+
+create persistent entity ChangeRefreshExample.Customer (
+  Name: string
+);
+/
+
+create microflow ChangeRefreshExample.RefreshChangedCustomer (
+  $Customer: ChangeRefreshExample.Customer
+)
+returns boolean
+begin
+  change $Customer (Name = 'Jane') refresh;
+  change $Customer refresh;
+  return true;
+end;
+/

mdl/ast/ast_microflow.go

@@ -192,9 +192,10 @@ func (s *CreateObjectStmt) isMicroflowStatement() {}
 
 // ChangeObjectStmt represents: CHANGE $Var (assignments)
 type ChangeObjectStmt struct {
-	Variable    string               // Variable name
-	Changes     []ChangeItem         // SET assignments
-	Annotations *ActivityAnnotations // Optional @position, @caption, @color, @annotation
+	Variable        string               // Variable name
+	Changes         []ChangeItem         // SET assignments
+	RefreshInClient bool                 // Whether to refresh in client
+	Annotations     *ActivityAnnotations // Optional @position, @caption, @color, @annotation
 }
 
 func (s *ChangeObjectStmt) isMicroflowStatement() {}

mdl/executor/cmd_microflows_builder_actions.go

@@ -239,14 +239,13 @@ func (fb *flowBuilder) addRollbackAction(s *ast.RollbackStmt) model.ID {
 
 // addChangeObjectAction creates a CHANGE statement.
 func (fb *flowBuilder) addChangeObjectAction(s *ast.ChangeObjectStmt) model.ID {
+	// Empty non-committing changes need RefreshInClient to satisfy Studio Pro
+	// consistency checks; explicit `refresh` keeps the same flag for all changes.
 	action := &microflows.ChangeObjectAction{
-		BaseElement:    model.BaseElement{ID: model.ID(types.GenerateID())},
-		ChangeVariable: s.Variable,
-		Commit:         microflows.CommitTypeNo,
-		// Studio Pro rejects an empty non-committing change action unless it
-		// refreshes in client. The CE0032 message mentions only items/commit,
-		// but mx check accepts RefreshInClient=true as the third valid escape.
-		RefreshInClient: len(s.Changes) == 0,
+		BaseElement:     model.BaseElement{ID: model.ID(types.GenerateID())},
+		ChangeVariable:  s.Variable,
+		Commit:          microflows.CommitTypeNo,
+		RefreshInClient: s.RefreshInClient || len(s.Changes) == 0,
 	}
 
 	// Look up entity type from variable scope

mdl/executor/cmd_microflows_builder_change_refresh_test.go

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+)
+
+func TestChangeObjectBuilderWritesRefreshInClient(t *testing.T) {
+	fb := &flowBuilder{}
+
+	fb.addChangeObjectAction(&ast.ChangeObjectStmt{
+		Variable:        "Customer",
+		RefreshInClient: true,
+		Changes: []ast.ChangeItem{
+			{Attribute: "Name", Value: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "Jane"}},
+		},
+	})
+
+	action := lastChangeObjectAction(t, fb)
+	if !action.RefreshInClient {
+		t.Fatal("Expected builder to write RefreshInClient")
+	}
+}
+
+func lastChangeObjectAction(t *testing.T, fb *flowBuilder) *microflows.ChangeObjectAction {
+	t.Helper()
+
+	if len(fb.objects) == 0 {
+		t.Fatal("Expected builder to create an action activity")
+	}
+	activity, ok := fb.objects[len(fb.objects)-1].(*microflows.ActionActivity)
+	if !ok {
+		t.Fatalf("Last object = %T, want ActionActivity", fb.objects[len(fb.objects)-1])
+	}
+	action, ok := activity.Action.(*microflows.ChangeObjectAction)
+	if !ok {
+		t.Fatalf("Action = %T, want ChangeObjectAction", activity.Action)
+	}
+	return action
+}

mdl/executor/cmd_microflows_format_action.go

@@ -241,8 +241,14 @@ func formatAction(
 				}
 				members = append(members, fmt.Sprintf("%s = %s", memberName, escapeExpressionValue(m.Value)))
 			}
+			if a.RefreshInClient {
+				return fmt.Sprintf("change $%s (%s) refresh;", varName, strings.Join(members, ", "))
+			}
 			return fmt.Sprintf("change $%s (%s);", varName, strings.Join(members, ", "))
 		}
+		if a.RefreshInClient {
+			return fmt.Sprintf("change $%s refresh;", varName)
+		}
 		return fmt.Sprintf("change $%s;", varName)
 
 	case *microflows.CommitObjectsAction:

mdl/executor/cmd_microflows_format_action_test.go

@@ -96,6 +96,30 @@ func TestFormatAction_ChangeObject_NoChanges(t *testing.T) {
 	}
 }
 
+func TestFormatAction_ChangeObject_WithRefresh(t *testing.T) {
+	e := newTestExecutor()
+	action := &microflows.ChangeObjectAction{
+		ChangeVariable:  "Customer",
+		RefreshInClient: true,
+		Changes: []*microflows.MemberChange{
+			{AttributeQualifiedName: "MyModule.Customer.Name", Value: "'Jane'"},
+		},
+	}
+	got := e.formatAction(action, nil, nil)
+	if got != "change $Customer (Name = 'Jane') refresh;" {
+		t.Errorf("got %q", got)
+	}
+}
+
+func TestFormatAction_ChangeObject_NoChangesWithRefresh(t *testing.T) {
+	e := newTestExecutor()
+	action := &microflows.ChangeObjectAction{ChangeVariable: "Obj", RefreshInClient: true}
+	got := e.formatAction(action, nil, nil)
+	if got != "change $Obj refresh;" {
+		t.Errorf("got %q", got)
+	}
+}
+
 func TestFormatAction_DeleteObject(t *testing.T) {
 	e := newTestExecutor()
 	action := &microflows.DeleteObjectAction{DeleteVariable: "Customer"}