docs: nanoflow BSON mapping, Go example, test cases, and validation fixes

- Add Nanoflow Mapping section to BSON mapping documentation
- Add create_nanoflow Go example with 4 nanoflow patterns
- Update CHANGELOG with JS action syntax and association retrieve entries
- Add nanoflow datasource option to create-page skill
- Update SDK_EQUIVALENCE nanoflow feature list
- Exhaustive nanoflow denylist test (21 disallowed + JS action allowed)
- Document denylist ordering dependency in error handling
- Fix isNumericLiteral: reject trailing dot ("5." → false)

Author: retran

.claude/skills/mendix/create-page.md

@@ -343,6 +343,7 @@ column colActions (caption: 'Actions') {
 | `datasource: database from Module.Entity` | Direct database query |
 | `datasource: $Variable` | Variable bound (requires DATAVIEW parent with entity) |
 | `datasource: microflow Module.GetData()` | Microflow datasource |
+| `datasource: nanoflow Module.GetData()` | Nanoflow datasource (client-side, no server roundtrip) |
 | `datasource: selection widgetName` | Listen to selection from another widget |
 | `datasource: association path` | Retrieve by association from context (ByAssociation) |
 | `datasource: $currentObject/Module.Assoc` | Sugar for `association` — same semantics, reads more naturally |

CHANGELOG.md

@@ -20,6 +20,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - **Nanoflow bug fixes** — Module existence validation for SHOW NANOFLOWS/MICROFLOWS, numeric return literals no longer get spurious `$` prefix, empty nanoflow/microflow names rejected at create time, `NanoflowCallAction` error handling type resolved correctly, `not()` expression spacing preserved on roundtrip, JavaScript action call rendering in DESCRIBE output
 - **Nanoflow diff support** — `mxcli diff` now detects and displays nanoflow changes (previously silently skipped)
+- **JavaScript action MDL syntax** — `call javascript action Module.ActionName(params)` now fully supported in CREATE NANOFLOW/MICROFLOW bodies: grammar, parser, builder, serializer, and roundtrip
+- **Association retrieve roundtrip fidelity** — `retrieve $X from $Y/Module.Association` syntax preserved on roundtrip (previously converted to `from Entity where Assoc = $Y`)
 - **DESCRIBE empty-then optimization** — If/else blocks with empty true branches are swapped and condition negated for readable output
 
 ### Changed

docs/05-mdl-specification/10-bson-mapping.md

@@ -1194,6 +1194,58 @@ Similar to CreateChangeAction but uses `microflows$ChangeAction`:
 
 ---
 
+## Nanoflow Mapping
+
+Nanoflows share the `Microflows` BSON domain — all action types, parameters, and flow structures are identical to microflows.
+
+### BSON Type
+
+| Unit Type | BSON `$Type` | Go Struct |
+|-----------|-------------|-----------|
+| Nanoflow | `Microflows$Nanoflow` | `microflows.Nanoflow` |
+
+### Key Differences from Microflow
+
+| Field | Microflow | Nanoflow |
+|-------|-----------|----------|
+| `$Type` | `Microflows$Microflow` | `Microflows$Nanoflow` |
+| `AllowConcurrentExecution` | Present | Absent |
+| `ConcurrencyErrorMicroflow` | Present | Absent |
+| `ConcurrenyErrorMessage` | Present | Absent |
+| `ApplyEntityAccess` | Present | Absent |
+
+All other fields — `ObjectCollection`, `Parameters`, `ReturnType`, `AllowedModuleRoles`, `Documentation`, `Excluded`, `MarkAsUsed` — are identical.
+
+### Allowed Actions
+
+Nanoflows run client-side. The following action types are **disallowed** in nanoflows:
+
+- `Microflows$CommitAction` — requires database (server-side)
+- `Microflows$RollbackAction` — requires database
+- `Microflows$DownloadFileAction` — requires server response
+- `Microflows$ImportMappingCallAction` — requires server context
+- `Microflows$ExportMappingCallAction` — requires server context
+- `Microflows$RestCallAction` — use JavaScript actions for HTTP from client
+- `Microflows$WebServiceCallAction` — server-side only
+
+The following are **nanoflow-specific** (allowed only in nanoflows):
+
+- `Microflows$SynchronizeAction` — triggers offline data sync
+
+### JavaScript Action Calls
+
+JavaScript actions use `Microflows$JavaScriptActionCallAction` (not `JavaActionCallAction`):
+
+| Field | JavaAction | JavaScriptAction |
+|-------|-----------|-----------------|
+| `$Type` | `Microflows$JavaActionCallAction` | `Microflows$JavaScriptActionCallAction` |
+| Action reference | `JavaAction` | `JavaScriptAction` |
+| Result variable | `ResultVariableName` | `OutputVariableName` |
+| Parameter mapping type | `Microflows$JavaActionParameterMapping` | `Microflows$JavaScriptActionParameterMapping` |
+| Parameter value key | `Value` | `ParameterValue` |
+
+---
+
 ## Debugging BSON Issues
 
 When Studio Pro doesn't display data correctly (e.g., missing attributes, incorrect values), follow this debugging approach:

docs/11-proposals/SDK_EQUIVALENCE.md

@@ -153,7 +153,7 @@ modelsdk-go/
 | Attribute types | ✅ Complete | 9 types |
 | Association CRUD | ✅ Complete | |
 | Microflow basic | ⚠️ Partial | Basic structure only |
-| Nanoflow CRUD | ⚠️ Partial | CREATE/DROP/DESCRIBE/SHOW/RENAME/MOVE, GRANT/REVOKE, diff support |
+| Nanoflow CRUD | ⚠️ Partial | CREATE/DROP/DESCRIBE/SHOW/RENAME/MOVE, GRANT/REVOKE, diff, JavaScript action calls, association retrieve roundtrip |
 | Page basic | ⚠️ Partial | Basic structure only |
 | JSON export | ✅ Complete | |
 

docs/15-testing/nanoflow-test-cases.md

@@ -28,15 +28,15 @@ Total: 223 nanoflows across 3 projects.
 ### 2. Build mxcli
 
 ```bash
-cd ~/workspace/mxcli
 git checkout pr4-nanoflows-all
 make build && make test && make lint-go
 ```
 
 ### 3. Smoke test
 
 ```bash
-for mpr in ~/workspace/mendix-apps/*/*.mpr; do
+APPS_DIR=<path-to-extracted-apps>
+for mpr in "$APPS_DIR"/*/*.mpr; do
   echo "=== $(basename $(dirname $mpr)) ==="
   echo "show nanoflows;" > /tmp/show-nf.mdl
   mxcli exec /tmp/show-nf.mdl -p "$mpr" 2>&1 | tail -1
@@ -48,7 +48,7 @@ Expected: 79, 93, 51 nanoflows respectively.
 ### 4. Interactive testing
 
 ```bash
-mxcli repl -p ~/workspace/mendix-apps/EnquiriesManagement/EnquiriesManagement.mpr
+mxcli repl -p <path-to-app>/EnquiriesManagement.mpr
 ```
 
 ### 5. Script-based testing
@@ -57,7 +57,18 @@ mxcli repl -p ~/workspace/mendix-apps/EnquiriesManagement/EnquiriesManagement.mp
 mxcli exec test-sequence.mdl -p <mpr>
 ```
 
-Write operations (CREATE, DROP, GRANT/REVOKE) modify the `.mpr`. Back up before destructive tests.
+Write operations (CREATE, DROP, GRANT/REVOKE) modify the `.mpr` file **in place**.
+
+> **IMPORTANT:** Always run destructive tests against a **copy** of the project folder,
+> never the original. The `.mpr` file references other files in the project directory,
+> and nanoflows that are DROPped cannot be recovered — there is no undo, no git history,
+> and no Studio Pro autosave for `.mpr` files.
+>
+> ```bash
+> # Before each destructive test session
+> cp -r MyProject MyProject-test
+> mxcli repl -p MyProject-test/MyProject.mpr
+> ```
 
 ---
 
@@ -421,6 +432,37 @@ end;
 ```
 **Expected:** Parses without error.
 
+### 6.7 Call JavaScript action — simple
+```
+create nanoflow MyModule.JSTest () returns Boolean
+begin
+  $Result = call javascript action NanoflowCommons.HasConnectivity ();
+end;
+```
+**Expected:** Parses, creates. DESCRIBE preserves `call javascript action` syntax.
+
+### 6.8 Call JavaScript action — with parameters
+```
+create nanoflow MyModule.JSWithParams () returns Boolean
+begin
+  $Result = call javascript action NanoflowCommons.SignIn (userName = 'test', password = 'pass');
+end;
+```
+**Expected:** Parameter mappings preserved in DESCRIBE.
+
+### 6.9 Call JavaScript action — roundtrip
+1. DESCRIBE an existing nanoflow that calls a JavaScript action (e.g. `Atlas_Web_Content.ACT_Login`)
+2. Capture MDL output
+3. DROP the nanoflow
+4. Execute captured MDL (CREATE OR MODIFY)
+5. DESCRIBE again
+6. Compare — `call javascript action` syntax preserved. Only expected diff: `on error rollback` appended (default error handling)
+
+### 6.10 Call JavaScript action — cross-module
+Test calling a JS action defined in a different module (e.g. `NanoflowCommons.SignIn` from `Atlas_Web_Content`).
+
+**Expected:** Qualified action name preserved across modules.
+
 ---
 
 ## 7. GRANT / REVOKE EXECUTE ON NANOFLOW
@@ -689,13 +731,17 @@ create nanoflow M.BadReturn () returns NonExistent.MyEnum begin end;
 3. DESCRIBE — verify original version preserved
 
 ### 16.5 BSON roundtrip data integrity
-For 10+ complex nanoflows (error handling, annotations, 10+ activities, multiple parameter types):
+For 10+ complex nanoflows (error handling, annotations, 10+ activities, multiple parameter types, JavaScript action calls, association retrieves):
 1. DESCRIBE → capture
 2. DROP
 3. Execute captured MDL
 4. DESCRIBE → capture again
 5. Diff — any difference is a data loss bug
 
+Include nanoflows with:
+- `call javascript action` actions (verify syntax preserved, not lost)
+- `retrieve $X from $Y/Module.Association` actions (verify association syntax preserved, not converted to database retrieve)
+
 ### 16.6 Double DROP
 ```
 drop nanoflow M.X;

examples/create_nanoflow/main.go

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Example: Creating Nanoflows using MDL
+//
+// This example demonstrates how to create nanoflows programmatically
+// using the MDL (Mendix Definition Language) executor. Nanoflows run
+// client-side and support JavaScript action calls, show page/message
+// actions, and other client-compatible activities.
+//
+// There are two ways to create nanoflows:
+// 1. Using MDL via the mxcli command line (recommended for scripts)
+// 2. Using MDL programmatically via the executor (shown here)
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/mdl/backend"
+	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
+	"github.com/mendixlabs/mxcli/mdl/executor"
+	"github.com/mendixlabs/mxcli/mdl/visitor"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Println("Usage: create_nanoflow <path-to-mpr-file>")
+		fmt.Println()
+		fmt.Println("This example creates several nanoflows demonstrating different patterns.")
+		fmt.Println("WARNING: This will modify the MPR file! Make a backup first.")
+		fmt.Println()
+		fmt.Println("Prerequisites:")
+		fmt.Println("  - A module named 'MyModule' (or modify the code)")
+		os.Exit(1)
+	}
+
+	mprPath := os.Args[1]
+
+	// Create the MDL executor with stdout for output
+	exec := executor.New(os.Stdout)
+	exec.SetBackendFactory(func() backend.FullBackend { return mprbackend.New() })
+
+	// Define MDL script with several nanoflow examples
+	mdlScript := fmt.Sprintf(`
+-- Connect to the Mendix project
+CONNECT '%s';
+
+-- 1. Minimal nanoflow (no parameters, no return)
+create nanoflow MyModule.NF_HelloWorld ()
+begin
+  show message 'Hello from a nanoflow!';
+end;
+
+-- 2. Nanoflow with parameters and return type
+create nanoflow MyModule.NF_IsValidInput (Input : String) returns Boolean
+begin
+  if length($Input) > 0 then
+    return true;
+  else
+    return false;
+  end if;
+end;
+
+-- 3. Nanoflow calling a JavaScript action
+create nanoflow MyModule.NF_CheckConnectivity () returns Boolean
+begin
+  $IsOnline = call javascript action NanoflowCommons.HasConnectivity ();
+  return $IsOnline;
+end;
+
+-- 4. Nanoflow calling another nanoflow
+create nanoflow MyModule.NF_ValidateAndCheck (Input : String) returns Boolean
+begin
+  $IsValid = call nanoflow MyModule.NF_IsValidInput (Input = $Input);
+  if $IsValid then
+    $IsOnline = call nanoflow MyModule.NF_CheckConnectivity ();
+    return $IsOnline;
+  else
+    return false;
+  end if;
+end;
+
+-- 5. Grant access to a role
+grant execute on nanoflow MyModule.NF_HelloWorld to MyModule.User;
+grant execute on nanoflow MyModule.NF_ValidateAndCheck to MyModule.User;
+
+-- Verify: list all nanoflows in the module
+show nanoflows MyModule;
+
+-- Verify: describe a nanoflow
+describe nanoflow MyModule.NF_ValidateAndCheck;
+
+DISCONNECT;
+`, mprPath)
+
+	// Parse the MDL script
+	fmt.Println("Parsing MDL script...")
+	prog, errs := visitor.Build(mdlScript)
+	if len(errs) > 0 {
+		fmt.Printf("Parse errors:\n")
+		for _, err := range errs {
+			fmt.Printf("  - %v\n", err)
+		}
+		os.Exit(1)
+	}
+
+	// Execute
+	fmt.Println("\nExecuting MDL:")
+	fmt.Println(strings.TrimSpace(mdlScript))
+	fmt.Println()
+
+	err := exec.ExecuteProgram(prog)
+	if err != nil {
+		fmt.Printf("Error executing MDL: %v\n", err)
+		fmt.Println("\nTip: Make sure the module exists in your project.")
+		os.Exit(1)
+	}
+
+	fmt.Println("\nNanoflows created successfully!")
+
+	// =========================================================================
+	// Alternative: Using mxcli command line
+	// =========================================================================
+	fmt.Println("\n" + strings.Repeat("=", 60))
+	fmt.Println("Alternative: Using mxcli command line")
+	fmt.Println(strings.Repeat("=", 60))
+	fmt.Println()
+	fmt.Printf("  echo 'create nanoflow MyModule.NF_Test () begin show message '\"'\"'Hello!'\"'\"'; end;' | mxcli exec -p %s /dev/stdin\n", mprPath)
+	fmt.Println()
+	fmt.Println("Or with a script file:")
+	fmt.Println()
+	fmt.Printf("  mxcli exec -p %s nanoflows.mdl\n", mprPath)
+}

mdl/executor/cmd_microflows_format_action.go

@@ -1170,7 +1170,7 @@ func isNumericLiteral(s string) bool {
 			return false
 		}
 	}
-	return hasDigit
+	return hasDigit && s[len(s)-1] != '.'
 }
 
 // formatImportXmlAction formats an import mapping action as MDL.

mdl/executor/cmd_microflows_format_action_test.go

@@ -756,6 +756,11 @@ func TestIsNumericLiteral(t *testing.T) {
 		{"$42", false},
 		{"1.2.3", false},
 		{"42abc", false},
+		{".", false},
+		{"-.", false},
+		{"5.", false},
+		{".5", true},
+		{"-.5", true},
 	}
 	for _, tt := range tests {
 		got := isNumericLiteral(tt.input)

mdl/executor/cmd_nanoflows_mock_test.go

@@ -303,6 +303,9 @@ func TestShowAccessOnNanoflow_Mock_NotFound(t *testing.T) {
 // --- NANOFLOW VALIDATION ---
 
 func TestValidateNanoflowBody_DisallowedActions(t *testing.T) {
+	// EXHAUSTIVE: every type in checkDisallowedNanoflowAction must appear here.
+	// If a new server-side action is added to the AST but not to the denylist,
+	// add it here so the test fails visibly.
 	tests := []struct {
 		name string
 		stmt ast.MicroflowStatement
@@ -311,9 +314,24 @@ func TestValidateNanoflowBody_DisallowedActions(t *testing.T) {
 		{"RaiseError", &ast.RaiseErrorStmt{}, "ErrorEvent"},
 		{"JavaAction", &ast.CallJavaActionStmt{}, "Java"},
 		{"DatabaseQuery", &ast.ExecuteDatabaseQueryStmt{}, "database"},
+		{"CallExternalAction", &ast.CallExternalActionStmt{}, "external action"},
 		{"ShowHomePage", &ast.ShowHomePageStmt{}, "SHOW HOME PAGE"},
 		{"RestCall", &ast.RestCallStmt{}, "REST"},
+		{"SendRestRequest", &ast.SendRestRequestStmt{}, "REST"},
+		{"ImportFromMapping", &ast.ImportFromMappingStmt{}, "import mapping"},
+		{"ExportToMapping", &ast.ExportToMappingStmt{}, "export mapping"},
+		{"TransformJson", &ast.TransformJsonStmt{}, "JSON transformation"},
 		{"CallWorkflow", &ast.CallWorkflowStmt{}, "workflow"},
+		{"GetWorkflowData", &ast.GetWorkflowDataStmt{}, "workflow"},
+		{"GetWorkflows", &ast.GetWorkflowsStmt{}, "workflow"},
+		{"GetWorkflowActivityRecords", &ast.GetWorkflowActivityRecordsStmt{}, "workflow"},
+		{"WorkflowOperation", &ast.WorkflowOperationStmt{}, "workflow"},
+		{"SetTaskOutcome", &ast.SetTaskOutcomeStmt{}, "workflow"},
+		{"OpenUserTask", &ast.OpenUserTaskStmt{}, "workflow"},
+		{"NotifyWorkflow", &ast.NotifyWorkflowStmt{}, "workflow"},
+		{"OpenWorkflow", &ast.OpenWorkflowStmt{}, "workflow"},
+		{"LockWorkflow", &ast.LockWorkflowStmt{}, "workflow"},
+		{"UnlockWorkflow", &ast.UnlockWorkflowStmt{}, "workflow"},
 	}
 
 	for _, tt := range tests {
@@ -338,6 +356,7 @@ func TestValidateNanoflowBody_AllowedActions(t *testing.T) {
 		{"ShowPage", &ast.ShowPageStmt{}},
 		{"CallMicroflow", &ast.CallMicroflowStmt{}},
 		{"CallNanoflow", &ast.CallNanoflowStmt{}},
+		{"CallJavaScriptAction", &ast.CallJavaScriptActionStmt{}},
 		{"CreateVariable", &ast.DeclareStmt{}},
 		{"ChangeVariable", &ast.MfSetStmt{}},
 	}