form0-core 0.3.1 → 0.4.1

package/src/builtins/choice/choicevalue.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { CHOICEVALUE_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin CHOICEVALUE
- * @description Retrieves the currently selected choice field value, preserving the type (if the value is a number preserves the number type, otherwise string). If no selection it returns null.
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {Object} choiceField - The choice field object with choice and other arrays
  * @returns {*} The selected choice value with preserved type, or null if no selection
- * @example
- * // Get the selected city value
- * CHOICEVALUE($city)
- * @example
- * // Use in conditional logic
- * IF(CHOICEVALUE($city) === "bogota", "Welcome to Bogotá!", "Welcome!")
  */
-export const CHOICEVALUE_METADATA = defineBuiltinMetadata({
-  name: 'CHOICEVALUE',
-  category: 'choice',
-  signature: 'CHOICEVALUE(fieldValue)',
-  description: 'Return the selected choice value from a choice field.',
-  examples: [
-    'CHOICEVALUE($city)',
-    'IF(CHOICEVALUE($city) === "bogota", "Welcome to Bogota!", "Welcome!")',
-  ],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
-});
-
 export const CHOICEVALUE = (choiceField) => {
   // Handle null/undefined input
   if (!choiceField || typeof choiceField !== 'object') {

package/src/builtins/choice/choicevalues.js

@@ -1,26 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { CHOICEVALUES_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin CHOICEVALUES
- * @description Retrieves an array of all selected choice field values from a MultiChoiceField, preserving the type of each value. Returns an empty array if no selections.
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {Object} multiChoiceField - The multi choice field object with choices and other arrays
  * @returns {Array} Array of selected choice values with preserved types
- * @example
- * // Get all selected color values
- * CHOICEVALUES($colors)
- * @example
- * // Check if "red" is selected
- * CHOICEVALUES($colors).includes("red")
  */
-export const CHOICEVALUES_METADATA = defineBuiltinMetadata({
-  name: 'CHOICEVALUES',
-  category: 'choice',
-  signature: 'CHOICEVALUES(fieldValue)',
-  description: 'Return all selected values from a MultiChoiceField.',
-  examples: ['CHOICEVALUES($colors)', 'CHOICEVALUES($colors).includes("red")'],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
-});
-
 export const CHOICEVALUES = (multiChoiceField) => {
   // Handle null/undefined input
   if (!multiChoiceField || typeof multiChoiceField !== 'object') {

package/src/builtins/choice/hasother.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { HASOTHER_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin HASOTHER
- * @description Returns true if user entered an other option, false otherwise. Works with both SingleChoiceField and MultiChoiceField.
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {Object} choiceField - The choice field object (SingleChoiceField with choice array or MultiChoiceField with choices array) and other array
  * @returns {boolean} True if user entered an other option, false otherwise
- * @example
- * // Check if user entered other option in single choice field
- * HASOTHER($city)
- * @example
- * // Check if user entered other option in multi choice field
- * HASOTHER($colors)
- * @example
- * // Use in conditional logic
- * IF(HASOTHER($city), "Custom city: " + OTHER($city), "Selected city: " + CHOICELABEL($city))
  */
-export const HASOTHER_METADATA = defineBuiltinMetadata({
-  name: 'HASOTHER',
-  category: 'choice',
-  signature: 'HASOTHER(fieldValue)',
-  description: 'Return true when the field has an "other" value.',
-  examples: ['HASOTHER($city)'],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
-});
-
 export const HASOTHER = (choiceField) => {
   // Handle null/undefined input
   if (!choiceField || typeof choiceField !== 'object') {

package/src/builtins/choice/other.js

@@ -1,29 +1,11 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { OTHER_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin OTHER
- * @description Retrieves the other label if user entered the other option, otherwise null. Works with both SingleChoiceField and MultiChoiceField.
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {Object} choiceField - The choice field object (SingleChoiceField with choice array or MultiChoiceField with choices array) and other array
  * @returns {string|null} The other label if user entered an other option, null otherwise
- * @example
- * // Get the other value from single choice field
- * OTHER($city)
- * @example
- * // Get the other value from multi choice field
- * OTHER($colors)
- * @example
- * // Use in conditional logic
- * IF(HASOTHER($city), "Custom city: " + OTHER($city), "No custom city entered")
  */
-export const OTHER_METADATA = defineBuiltinMetadata({
-  name: 'OTHER',
-  category: 'choice',
-  signature: 'OTHER(fieldValue)',
-  description: 'Return the "other" label from a choice field.',
-  examples: ['OTHER($city)'],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
-});
-
 export const OTHER = (choiceField) => {
   // Handle null/undefined input
   if (!choiceField || typeof choiceField !== 'object') {

package/src/builtins/control/eval.js

@@ -1,40 +1,33 @@
 import { validateExpression } from '../../security/validation.js';
 import { SAFE_SECURITY_CONFIG } from '../../security/config.js';
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { EVAL_METADATA } from '../builtin-definitions.js';
 
 /**
  * @builtin EVAL
- * @description Evaluates a dynamic expression in a controlled, secure context
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {string} expression - The dynamic expression to evaluate
  * @returns {*} The result of the evaluated expression
- * @example
- * // Dynamic field access
- * EVAL('$' + dynamicFieldName)
- * @example
- * // Dynamic builtin calls
- * EVAL('CHOICEVALUE($' + fieldVar + ')')
- * @example
- * // Computed field references
- * EVAL('$city' + '_suffix')
  */
-export const EVAL_METADATA = defineBuiltinMetadata({
-  name: 'EVAL',
-  category: 'control',
-  signature: 'EVAL(expression)',
-  description: 'Evaluate a dynamically built expression string in a restricted context.',
-  examples: ['EVAL("$" + dynamicFieldName)'],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
-});
-
 // Global context for EVAL() - set during expression evaluation
 let _evalContext = null;
+let _evalReporting = null;
 
 /**
  * Set the context for EVAL() during expression evaluation
  * Called internally by the expression evaluator
  */
-export function __setEvalContext(context) {
+export function __setEvalContext(context, reporting = null) {
+  const previousContext = _evalContext;
+  const previousReporting = _evalReporting;
   _evalContext = context;
+  _evalReporting = reporting;
+  let restored = false;
+  return () => {
+    if (restored) return;
+    restored = true;
+    _evalContext = previousContext;
+    _evalReporting = previousReporting;
+  };
 }
 
 /**
@@ -43,24 +36,54 @@ export function __setEvalContext(context) {
  */
 export function __clearEvalContext() {
   _evalContext = null;
+  _evalReporting = null;
+}
+
+function reportFailure(code, phase, message, consoleArgs, context = {}) {
+  _evalReporting?.onDiagnostic?.({
+    code,
+    phase,
+    message,
+    context: { source: 'EVAL', ...context },
+  });
+  if (!_evalReporting?.suppressConsole) console.warn(...consoleArgs);
+}
+
+function logDebug(...args) {
+  if (!_evalReporting?.suppressConsole) console.log(...args);
+}
+
+function referenceContext(reference) {
+  // Legacy EVAL also treats strings starting with '$' as reference lookups.
+  // Do not copy a whole expression into diagnostic metadata in that case.
+  return /^\$[a-zA-Z_][a-zA-Z0-9_]*$/.test(reference)
+    ? { referencedFieldName: reference.slice(1) }
+    : {};
 }
 
 export const EVAL = (expression) => {
   // Step 1: Basic validation
   if (typeof expression !== 'string') {
-    console.warn('[form0] EVAL() requires a string expression');
+    reportFailure('eval_invalid_argument', 'validation', 'EVAL() requires a string expression', [
+      '[form0] EVAL() requires a string expression',
+    ]);
     return null;
   }
 
   if (!expression || expression.trim() === '') {
-    console.warn('[form0] EVAL() requires a non-empty expression');
+    reportFailure('eval_invalid_argument', 'validation', 'EVAL() requires a non-empty expression', [
+      '[form0] EVAL() requires a non-empty expression',
+    ]);
     return null;
   }
 
   // Step 2: Security validation for EVAL() expressions
   const securityValidation = validateEvalExpression(expression);
   if (!securityValidation.valid) {
-    console.warn('[form0] EVAL() security validation failed:', securityValidation.reason);
+    reportFailure('expression_validation_failed', 'validation', securityValidation.reason, [
+      '[form0] EVAL() security validation failed:',
+      securityValidation.reason,
+    ]);
     return null;
   }
 
@@ -147,12 +170,13 @@ function validateEvalExpression(expression) {
  * @returns {*} The evaluation result
  */
 function evaluateHybridExpression(expression, formContext) {
+  let phase = 'runtime';
   try {
     // Step 3a: Handle simple string literals and field references directly
     if (isSimpleStringLiteral(expression)) {
       // Simple string literal - return as is
       const result = expression;
-      console.log('[form0] EVAL() simple string:', expression, '→', result);
+      logDebug('[form0] EVAL() simple string:', expression, '→', result);
       return result;
     }
 
@@ -160,10 +184,16 @@ function evaluateHybridExpression(expression, formContext) {
       // Field reference - resolve from context
       const fieldValue = formContext?.[expression];
       if (fieldValue !== undefined) {
-        console.log('[form0] EVAL() resolved field reference:', expression, '→', fieldValue);
+        logDebug('[form0] EVAL() resolved field reference:', expression, '→', fieldValue);
         return fieldValue;
       } else {
-        console.warn('[form0] EVAL() field reference not found:', expression);
+        reportFailure(
+          'eval_reference_unavailable',
+          'scope',
+          'EVAL() field reference is unavailable.',
+          ['[form0] EVAL() field reference not found:', expression],
+          referenceContext(expression)
+        );
         return null;
       }
     }
@@ -183,7 +213,9 @@ function evaluateHybridExpression(expression, formContext) {
     const keys = Object.keys(basicContext);
     const values = Object.values(basicContext);
 
+    phase = 'syntax';
     const fn = new Function(...keys, `return (${expression});`);
+    phase = 'runtime';
     const result = fn(...values);
 
     // Step 3e: Check if result should be resolved as field reference
@@ -191,7 +223,7 @@ function evaluateHybridExpression(expression, formContext) {
       // This is a field reference - resolve it from context
       const fieldValue = formContext?.[result];
       if (fieldValue !== undefined) {
-        console.log(
+        logDebug(
           '[form0] EVAL() resolved field reference:',
           expression,
           '→',
@@ -201,16 +233,31 @@ function evaluateHybridExpression(expression, formContext) {
         );
         return fieldValue;
       } else {
-        console.warn('[form0] EVAL() field reference not found:', result);
+        reportFailure(
+          'eval_reference_unavailable',
+          'scope',
+          'EVAL() field reference is unavailable.',
+          ['[form0] EVAL() field reference not found:', result],
+          referenceContext(result)
+        );
         return null;
       }
     }
 
     // Step 3f: Return string result for dataname references
-    console.log('[form0] EVAL() built string:', expression, '→', result);
+    logDebug('[form0] EVAL() built string:', expression, '→', result);
     return result;
   } catch (error) {
-    console.warn('[form0] EVAL() execution failed:', error.message);
+    reportFailure(
+      phase === 'syntax'
+        ? error instanceof SyntaxError
+          ? 'invalid_syntax'
+          : 'compilation_error'
+        : 'runtime_exception',
+      phase,
+      error instanceof Error && error.message ? error.message : 'Unknown EVAL() runtime error.',
+      ['[form0] EVAL() execution failed:', error.message]
+    );
     return null;
   }
 }

package/src/builtins/control/setresult.js

@@ -1,30 +1,16 @@
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+export { SETRESULT_METADATA } from '../builtin-definitions.js';
 
 // Global state for result management
 let _resultSet = false;
 let _resultValue;
+let _resultScopeDepth = 0;
 
 /**
  * @builtin SETRESULT
- * @description Sets a result value that can be consumed by the form engine
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * @param {*} value - The value to set as the result
  * @returns {*} The same value that was passed in
- * @example
- * // Set a calculation result
- * SETRESULT(price * quantity * (1 + taxRate))
- * @example
- * // Set a conditional result
- * SETRESULT(IF(isEligible, discount, 0))
  */
-export const SETRESULT_METADATA = defineBuiltinMetadata({
-  name: 'SETRESULT',
-  category: 'control',
-  signature: 'SETRESULT(value)',
-  description: 'Set the final return value for multiline calculations.',
-  examples: ['SETRESULT($price * $quantity)'],
-  contexts: [BUILTIN_CONTEXTS.CALCULATION],
-});
-
 export const SETRESULT = (value) => {
   _resultSet = true;
   _resultValue = value;
@@ -43,6 +29,32 @@ export function __consumeResult() {
   return { called, value };
 }
 
+/**
+ * Start an isolated synchronous result scope and return its restoration function.
+ * Nested scopes restore the enclosing SETRESULT state; top-level scopes retain the
+ * legacy behavior of clearing stale state at both evaluation boundaries.
+ * @returns {() => void}
+ */
+export function __beginResultScope() {
+  const previous = { called: _resultSet, value: _resultValue };
+  const restorePrevious = _resultScopeDepth > 0;
+  _resultScopeDepth += 1;
+  __resetResult();
+
+  let restored = false;
+  return () => {
+    if (restored) return;
+    restored = true;
+    _resultScopeDepth = Math.max(0, _resultScopeDepth - 1);
+    if (restorePrevious) {
+      _resultSet = previous.called;
+      _resultValue = previous.value;
+    } else {
+      __resetResult();
+    }
+  };
+}
+
 /** Clear calculation result state without consuming it. */
 export function __resetResult() {
   _resultSet = false;

package/src/builtins/date/dateadd.js

@@ -0,0 +1,24 @@
+import { formatIsoDate, isBlankDateArgument, parseIsoDate } from '../../utilities/date-utils.js';
+
+export { DATEADD_METADATA } from '../builtin-definitions.js';
+
+/**
+ * @builtin DATEADD
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
+ * @param {string | null} date - A YYYY-MM-DD date
+ * @param {number | null} days - Whole number of days to add; negative values subtract
+ * @returns {string | null} The resulting YYYY-MM-DD date, or null when an argument is blank
+ */
+export const DATEADD = (date, days) => {
+  if (isBlankDateArgument(date) || isBlankDateArgument(days)) return null;
+
+  const dayNumber = parseIsoDate(date);
+  if (dayNumber === null) {
+    throw new Error('DATEADD requires a date in YYYY-MM-DD format');
+  }
+  if (!Number.isInteger(days)) {
+    throw new Error('DATEADD requires a whole number of days');
+  }
+
+  return formatIsoDate(dayNumber + days);
+};

package/src/builtins/date/days.js

@@ -0,0 +1,22 @@
+import { isBlankDateArgument, parseIsoDate } from '../../utilities/date-utils.js';
+
+export { DAYS_METADATA } from '../builtin-definitions.js';
+
+/**
+ * @builtin DAYS
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
+ * @param {string | null} endDate - A YYYY-MM-DD date
+ * @param {string | null} startDate - A YYYY-MM-DD date
+ * @returns {number | null} Days from startDate to endDate, or null when an argument is blank
+ */
+export const DAYS = (endDate, startDate) => {
+  if (isBlankDateArgument(endDate) || isBlankDateArgument(startDate)) return null;
+
+  const end = parseIsoDate(endDate);
+  const start = parseIsoDate(startDate);
+  if (end === null || start === null) {
+    throw new Error('DAYS requires dates in YYYY-MM-DD format');
+  }
+
+  return end - start;
+};

package/src/builtins/event/control/off.js

@@ -1,9 +1,10 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
+export { OFF_METADATA } from '../../builtin-definitions.js';
 import { isValidEventType } from '../../../engine/event-registry.js';
 
 /**
- * OFF builtin for form events
+ * @builtin OFF
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * Removes event handlers within event context
  * Automatically collects operation for platform execution
  *
@@ -11,32 +12,7 @@ import { isValidEventType } from '../../../engine/event-registry.js';
  * @param {string|Function} [fieldKeyOrCallback] - Field key for field events, or callback for global events
  * @param {Function} [callback] - Callback function for field events (when fieldKeyOrCallback is a field key)
  * @returns {Object} Operation descriptor for platform execution (for backward compatibility)
- *
- * @example
- * // Remove specific global event handler
- * OFF('load-record', specificCallback);
- *
- * @example
- * // Remove all global event handlers
- * OFF('load-record');
- *
- * @example
- * // Remove specific field event handler
- * OFF('change', 'city', specificCallback);
- *
- * @example
- * // Remove all field event handlers
- * OFF('change', 'city');
  */
-export const OFF_METADATA = defineBuiltinMetadata({
-  name: 'OFF',
-  category: 'event',
-  signature: 'OFF(eventType, fieldKeyOrCallback, callback)',
-  description: 'Remove event handlers within form event code.',
-  examples: ["OFF('change', 'city', specificCallback)"],
-  contexts: [BUILTIN_CONTEXTS.EVENT],
-});
-
 export function OFF(eventType, fieldKeyOrCallback, callback) {
   if (typeof eventType !== 'string' || eventType.trim().length === 0) {
     console.warn('[form0] OFF() requires a non-empty event type string');

package/src/builtins/event/control/on.js

@@ -1,9 +1,10 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
+export { ON_METADATA } from '../../builtin-definitions.js';
 import { isValidEventType } from '../../../engine/event-registry.js';
 
 /**
- * ON builtin for form events
+ * @builtin ON
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * Registers an event handler within event context
  * Automatically collects operation for platform execution
  *
@@ -11,24 +12,7 @@ import { isValidEventType } from '../../../engine/event-registry.js';
  * @param {string|Function} fieldKeyOrCallback - Field key for field events, or callback for global events
  * @param {Function} [callback] - Callback function for field events
  * @returns {Object} Operation descriptor for platform execution (for backward compatibility)
- *
- * @example
- * // Register global event handler
- * ON('load-record', function() { ALERT('Record loaded!'); });
- *
- * @example
- * // Register field-specific event handler
- * ON('change', 'city', function(event) { ALERT('City changed!'); });
  */
-export const ON_METADATA = defineBuiltinMetadata({
-  name: 'ON',
-  category: 'event',
-  signature: 'ON(eventType, fieldKeyOrCallback, callback)',
-  description: 'Register an event handler within form event code.',
-  examples: ["ON('change', 'city', function(event) { ALERT('City changed!'); })"],
-  contexts: [BUILTIN_CONTEXTS.EVENT],
-});
-
 export function ON(eventType, fieldKeyOrCallback, callback) {
   if (typeof eventType !== 'string' || eventType.trim().length === 0) {
     console.warn('[form0] ON() requires a non-empty event type string');

package/src/builtins/event/event-operations-collector.js

@@ -1,20 +1,44 @@
-// Global state for event operations collection
-let _eventOperations = [];
+let activeScope = null;
+let boundScope = null;
 
 /**
  * Internal function to collect event operations
  * @param {Object} operation - The operation descriptor to collect
  */
 export function __collectEventOperation(operation) {
-  _eventOperations.push(operation);
+  const scope = boundScope || activeScope;
+  scope?.collect(operation);
 }
 
 /**
- * Internal function to consume all collected event operations
- * @returns {Array} Array of collected operations
+ * Run synchronous event work with a dispatch-owned operation scope.
+ * @param {Object} scope - The scope receiving operations
+ * @param {Function} work - Synchronous work to execute
+ * @returns {*} The work result
  */
-export function __consumeEventOperations() {
-  const operations = [..._eventOperations]; // Copy array
-  _eventOperations = []; // Clear for next execution
-  return operations;
+export function __runWithEventOperationScope(scope, work) {
+  const enclosingScope = activeScope;
+  activeScope = scope;
+  try {
+    return work();
+  } finally {
+    activeScope = enclosingScope;
+  }
+}
+
+/**
+ * Invoke a canonical builtin with the scope it was bound to.
+ * @param {Object} scope - The builtin's originating scope
+ * @param {Function} builtin - Canonical event builtin
+ * @param {Array} args - Builtin arguments
+ * @returns {*} The builtin result
+ */
+export function __invokeBoundEventBuiltin(scope, builtin, args) {
+  const enclosingScope = boundScope;
+  boundScope = scope;
+  try {
+    return builtin(...args);
+  } finally {
+    boundScope = enclosingScope;
+  }
 }

package/src/builtins/event/field/setvalue.js

@@ -1,45 +1,16 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
+export { SETVALUE_METADATA } from '../../builtin-definitions.js';
 
 /**
- * SETVALUE builtin for form events
+ * @builtin SETVALUE
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * Sets a field value within event context
  * Automatically collects operation for platform execution
- * Supports multiple field types:
- * - TextField: string values
- * - NumericField: numeric values
- * - SingleChoiceField: string choice values
- * - MultiChoiceField: array of string choice values
  *
  * @param {string} fieldDataName - The data name of the field to set
  * @param {any} valueToSet - The value to set (string, number, array, etc.)
  * @returns {Object} Operation descriptor for platform execution (for backward compatibility)
- *
- * @example
- * // Set TextField value
- * SETVALUE('field_dataname', 'value_to_set')
- *
- * @example
- * // Set NumericField value
- * SETVALUE('field_dataname', 12)
- *
- * @example
- * // Set SingleChoiceField value
- * SETVALUE('field_dataname', 'choicefield_value_to_set')
- *
- * @example
- * // Set MultiChoiceField value
- * SETVALUE('field_dataname', ['value1', 'value2', 'value3'])
  */
-export const SETVALUE_METADATA = defineBuiltinMetadata({
-  name: 'SETVALUE',
-  category: 'event',
-  signature: 'SETVALUE(fieldDataName, valueToSet)',
-  description: 'Set a field value from a form event handler.',
-  examples: ["SETVALUE('field_dataname', 'value_to_set')"],
-  contexts: [BUILTIN_CONTEXTS.EVENT],
-});
-
 export function SETVALUE(fieldDataName, valueToSet) {
   // Create operation descriptor
   const operation = {

package/src/builtins/event/ui/alert.js

@@ -1,22 +1,14 @@
 import { __collectEventOperation } from '../event-operations-collector.js';
-import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../../builtin-metadata.js';
+export { ALERT_METADATA } from '../../builtin-definitions.js';
 
 /**
- * ALERT builtin for form events
+ * @builtin ALERT
+ * Name, signature, description, examples, and contexts: see builtin-definitions.js.
  * Automatically collects operation for platform execution
  * @param {string} title - The title to display in the alert
  * @param {string} message - The message to display in the alert (optional)
  * @returns {Object} Operation descriptor for platform execution (for backward compatibility)
  */
-export const ALERT_METADATA = defineBuiltinMetadata({
-  name: 'ALERT',
-  category: 'event',
-  signature: "ALERT(title, message = '')",
-  description: 'Display an alert from a form event handler.',
-  examples: ["ALERT('Saved', 'The record was saved successfully.')"],
-  contexts: [BUILTIN_CONTEXTS.EVENT],
-});
-
 export function ALERT(title, message = '') {
   // Create operation descriptor
   const operation = {