fix: event handler BSON field names and explicit parameter syntax

Parser: read from Events (not EventHandlers), Type (not Event),
SendInputParameter (not PassEventObject) with fallbacks for both.

Writer: emit DomainModels$EntityEvent (not DomainModels$EventHandler),
Type (not Event), SendInputParameter (not PassEventObject).

Grammar: event handlers now support ($currentObject) to pass the entity
object, or () to skip it. DESCRIBE shows the parameter explicitly and
only outputs RAISE ERROR on BEFORE handlers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

cmd/mxcli/help_topics/entity.txt

@@ -82,3 +82,29 @@ Complete Example:
   )
   INDEX (Email)
   COMMENT 'Stores customer information';
+
+Event Handlers:
+  ON BEFORE|AFTER CREATE|COMMIT|DELETE|ROLLBACK CALL Module.Microflow(...) [RAISE ERROR]
+
+  Parameter syntax:
+    ($currentObject)  - Microflow receives the entity object
+    ()                - Microflow receives no object parameter
+    (no parens)       - Same as ($currentObject), default
+
+  Rules:
+    - BEFORE handlers return Boolean. RAISE ERROR aborts when false.
+    - AFTER handlers return Void. Cannot use RAISE ERROR.
+
+  Add via ALTER ENTITY:
+    ALTER ENTITY MyModule.Customer
+      ADD EVENT HANDLER ON BEFORE COMMIT CALL MyModule.Validate($currentObject) RAISE ERROR;
+
+    ALTER ENTITY MyModule.Customer
+      ADD EVENT HANDLER ON AFTER COMMIT CALL MyModule.LogChange();
+
+  Or directly on CREATE ENTITY:
+    CREATE PERSISTENT ENTITY MyModule.Order (
+      Name: String(100)
+    )
+    ON BEFORE COMMIT CALL MyModule.ValidateOrder($currentObject) RAISE ERROR
+    ON AFTER COMMIT CALL MyModule.LogOrderChange($currentObject);

docs-site/src/language/alter-entity.md

@@ -111,6 +111,37 @@ ALTER ENTITY Sales.Order DROP STORE OWNER;
 ALTER ENTITY Sales.Order DROP STORE CHANGED DATE;
 ```
 
+## ADD/DROP EVENT HANDLER
+
+Register microflows to run before or after entity operations:
+
+```sql
+-- Before commit: validates and can abort (RAISE ERROR)
+ALTER ENTITY Sales.Order
+  ADD EVENT HANDLER ON BEFORE COMMIT CALL Sales.ValidateOrder($currentObject) RAISE ERROR;
+
+-- After commit: runs after successful commit (no RAISE ERROR)
+ALTER ENTITY Sales.Order
+  ADD EVENT HANDLER ON AFTER COMMIT CALL Sales.LogOrderChange($currentObject);
+
+-- Without passing the entity object
+ALTER ENTITY Sales.Order
+  ADD EVENT HANDLER ON AFTER CREATE CALL Sales.NotifyNewOrder();
+
+-- Remove an event handler
+ALTER ENTITY Sales.Order
+  DROP EVENT HANDLER ON BEFORE COMMIT;
+```
+
+| Moment | Returns | RAISE ERROR | Use case |
+|--------|---------|-------------|----------|
+| `BEFORE` | Boolean | Yes — aborts on `false` | Validation, permission checks |
+| `AFTER` | Void | No | Logging, notifications, side effects |
+
+Events: `CREATE`, `COMMIT`, `DELETE`, `ROLLBACK`
+
+Parameter: `($currentObject)` passes the entity to the microflow, `()` does not.
+
 ## Syntax Summary
 
 ```sql

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -64,7 +64,7 @@ Modifies an existing entity without full replacement.
 | Rename attribute | `ALTER ENTITY Module.Name RENAME OldName TO NewName;` | |
 | Add index | `ALTER ENTITY Module.Name ADD INDEX (Col1 [ASC\|DESC], ...);` | |
 | Drop index | `ALTER ENTITY Module.Name DROP INDEX (Col1, ...);` | |
-| Add event handler | `ALTER ENTITY Module.Name ADD EVENT HANDLER ON BEFORE COMMIT CALL Mod.MF [RAISE ERROR];` | Moments: BEFORE/AFTER, Events: CREATE/COMMIT/DELETE/ROLLBACK |
+| Add event handler | `ALTER ENTITY Module.Name ADD EVENT HANDLER ON BEFORE COMMIT CALL Mod.MF($currentObject) [RAISE ERROR];` | `($currentObject)` or `()`, RAISE ERROR only on BEFORE |
 | Drop event handler | `ALTER ENTITY Module.Name DROP EVENT HANDLER ON BEFORE COMMIT;` | |
 | Set documentation | `ALTER ENTITY Module.Name SET DOCUMENTATION 'text';` | |
 | Set position | `ALTER ENTITY Module.Name SET POSITION (100, 200);` | Canvas position |

mdl-examples/doctype-tests/26-system-attribute-examples.mdl

@@ -70,3 +70,26 @@ CREATE OR MODIFY PERSISTENT ENTITY SysAttrTest.TempRecord (
 -- Disable both flags
 ALTER ENTITY SysAttrTest.TempRecord DROP STORE OWNER;
 ALTER ENTITY SysAttrTest.TempRecord DROP STORE CREATED DATE;
+
+-- ============================================================================
+-- Example 5: Entity with event handlers
+-- ============================================================================
+
+CREATE MICROFLOW SysAttrTest.ACT_ValidateOrder ($Order: SysAttrTest.AuditedRecord)
+RETURNS Boolean
+BEGIN
+  RETURN true;
+END;
+
+CREATE MICROFLOW SysAttrTest.ACT_AfterCommitOrder ($Order: SysAttrTest.AuditedRecord)
+BEGIN
+  RETURN empty;
+END;
+
+-- RAISE ERROR: only valid on BEFORE handlers (microflow returns Boolean, false = abort)
+ALTER ENTITY SysAttrTest.AuditedRecord
+  ADD EVENT HANDLER ON BEFORE COMMIT CALL SysAttrTest.ACT_ValidateOrder RAISE ERROR;
+
+-- AFTER handlers cannot RAISE ERROR (microflow returns Void)
+ALTER ENTITY SysAttrTest.AuditedRecord
+  ADD EVENT HANDLER ON AFTER COMMIT CALL SysAttrTest.ACT_AfterCommitOrder;

mdl/executor/cmd_entities_describe.go

@@ -401,18 +401,24 @@ func (e *Executor) describeEntity(name ast.QualifiedName) error {
 				if mfName == "" {
 					continue
 				}
-				raise := ""
-				if eh.RaiseErrorOnFalse {
-					raise = " RAISE ERROR"
-				}
 				eventName := string(eh.Event)
 				if eventName == "RollBack" {
 					eventName = "ROLLBACK"
 				} else {
 					eventName = strings.ToUpper(eventName)
 				}
-				fmt.Fprintf(e.output, "\nON %s %s CALL %s%s",
-					strings.ToUpper(string(eh.Moment)), eventName, mfName, raise)
+				// Show parameter: ($currentObject) or ()
+				paramStr := "()"
+				if eh.PassEventObject {
+					paramStr = "($currentObject)"
+				}
+				var options string
+				// RAISE ERROR only applies to Before handlers (they return Boolean)
+				if eh.RaiseErrorOnFalse && strings.EqualFold(string(eh.Moment), "Before") {
+					options = " RAISE ERROR"
+				}
+				fmt.Fprintf(e.output, "\nON %s %s CALL %s%s%s",
+					strings.ToUpper(string(eh.Moment)), eventName, mfName, paramStr, options)
 			}
 
 			fmt.Fprintln(e.output, ";")

mdl/grammar/MDLParser.g4

@@ -550,9 +550,10 @@ entityOption
     | eventHandlerDefinition
     ;
 
-// Entity event handler: ON BEFORE/AFTER CREATE/COMMIT/DELETE/ROLLBACK CALL Mod.Microflow [RAISE ERROR]
+// Entity event handler: ON BEFORE/AFTER CREATE/COMMIT/DELETE/ROLLBACK CALL Mod.Microflow($currentObject) [RAISE ERROR]
+// Empty parens () = don't pass object, ($currentObject) = pass object, no parens = pass object (default)
 eventHandlerDefinition
-    : ON eventMoment eventType CALL qualifiedName (RAISE ERROR)?
+    : ON eventMoment eventType CALL qualifiedName (LPAREN VARIABLE? RPAREN)? (RAISE ERROR)?
     ;
 
 eventMoment