form0-core 0.1.2 → 0.1.4

package/src/builtins/registry.js

@@ -1,99 +1,137 @@
-// Import all builtins
-import { IF } from './logical/if.js';
-import { AND } from './logical/and.js';
-import { OR } from './logical/or.js';
-import { COUNT } from './logical/count.js';
-import { COUNTA } from './logical/counta.js';
-import { COUNTBLANK } from './logical/countblank.js';
-import { ARRAY } from './logical/array.js';
-import { SETRESULT, __consumeResult } from './control/setresult.js';
-import { EVAL } from './control/eval.js';
-import { CHOICEVALUE } from './choice/choicevalue.js';
-import { CHOICELABEL } from './choice/choicelabel.js';
-import { HASOTHER } from './choice/hasother.js';
-import { OTHER } from './choice/other.js';
-import { CHOICEVALUES } from './choice/choicevalues.js';
-import { CHOICELABELS } from './choice/choicelabels.js';
-import { FORM } from './schema/form.js';
-import { DATANAMES } from './schema/datanames.js';
-import { ABS } from './math/abs.js';
-import { CEILING } from './math/ceiling.js';
-import { COS } from './math/cos.js';
-import { SIN } from './math/sin.js';
-import { ROUND } from './math/round.js';
-import { UPPER } from './string/upper.js';
+import { cloneBuiltinMetadata, BUILTIN_CONTEXTS } from './builtin-metadata.js';
 
-// Import event builtins
-import { ALERT } from './event/ui/alert.js';
-import { SETVALUE } from './event/field/setvalue.js';
-import { ON } from './event/control/on.js';
-import { OFF } from './event/control/off.js';
+import { IF, IF_METADATA } from './logical/if.js';
+import { AND, AND_METADATA } from './logical/and.js';
+import { OR, OR_METADATA } from './logical/or.js';
+import { COUNT, COUNT_METADATA } from './logical/count.js';
+import { COUNTA, COUNTA_METADATA } from './logical/counta.js';
+import { COUNTBLANK, COUNTBLANK_METADATA } from './logical/countblank.js';
+import { ARRAY, ARRAY_METADATA } from './logical/array.js';
+import { SETRESULT, SETRESULT_METADATA, __consumeResult } from './control/setresult.js';
+import { EVAL, EVAL_METADATA } from './control/eval.js';
+import { CHOICEVALUE, CHOICEVALUE_METADATA } from './choice/choicevalue.js';
+import { CHOICELABEL, CHOICELABEL_METADATA } from './choice/choicelabel.js';
+import { HASOTHER, HASOTHER_METADATA } from './choice/hasother.js';
+import { OTHER, OTHER_METADATA } from './choice/other.js';
+import { CHOICEVALUES, CHOICEVALUES_METADATA } from './choice/choicevalues.js';
+import { CHOICELABELS, CHOICELABELS_METADATA } from './choice/choicelabels.js';
+import { FORM, FORM_METADATA } from './schema/form.js';
+import { DATANAMES, DATANAMES_METADATA } from './schema/datanames.js';
+import { ABS, ABS_METADATA } from './math/abs.js';
+import { CEILING, CEILING_METADATA } from './math/ceiling.js';
+import { COS, COS_METADATA } from './math/cos.js';
+import { SIN, SIN_METADATA } from './math/sin.js';
+import { ROUND, ROUND_METADATA } from './math/round.js';
+import { UPPER, UPPER_METADATA } from './string/upper.js';
+
+import { ALERT, ALERT_METADATA } from './event/ui/alert.js';
+import { SETVALUE, SETVALUE_METADATA } from './event/field/setvalue.js';
+import { ON, ON_METADATA } from './event/control/on.js';
+import { OFF, OFF_METADATA } from './event/control/off.js';
 import { __consumeEventOperations } from './event/event-operations-collector.js';
 
-// Export individual builtins
-export { IF } from './logical/if.js';
-export { AND } from './logical/and.js';
-export { OR } from './logical/or.js';
-export { COUNT } from './logical/count.js';
-export { COUNTA } from './logical/counta.js';
-export { COUNTBLANK } from './logical/countblank.js';
-export { ARRAY } from './logical/array.js';
-export { SETRESULT, __consumeResult } from './control/setresult.js';
-export { EVAL, __setEvalContext, __clearEvalContext } from './control/eval.js';
-export { CHOICEVALUE } from './choice/choicevalue.js';
-export { CHOICELABEL } from './choice/choicelabel.js';
-export { HASOTHER } from './choice/hasother.js';
-export { OTHER } from './choice/other.js';
-export { CHOICEVALUES } from './choice/choicevalues.js';
-export { CHOICELABELS } from './choice/choicelabels.js';
-export { FORM } from './schema/form.js';
-export { DATANAMES, __setDataNamesContext, __clearDataNamesContext } from './schema/datanames.js';
-export { ABS } from './math/abs.js';
-export { CEILING } from './math/ceiling.js';
-export { COS } from './math/cos.js';
-export { SIN } from './math/sin.js';
-export { ROUND } from './math/round.js';
-export { UPPER } from './string/upper.js';
+export { IF, IF_METADATA } from './logical/if.js';
+export { AND, AND_METADATA } from './logical/and.js';
+export { OR, OR_METADATA } from './logical/or.js';
+export { COUNT, COUNT_METADATA } from './logical/count.js';
+export { COUNTA, COUNTA_METADATA } from './logical/counta.js';
+export { COUNTBLANK, COUNTBLANK_METADATA } from './logical/countblank.js';
+export { ARRAY, ARRAY_METADATA } from './logical/array.js';
+export { SETRESULT, SETRESULT_METADATA, __consumeResult } from './control/setresult.js';
+export { EVAL, EVAL_METADATA, __setEvalContext, __clearEvalContext } from './control/eval.js';
+export { CHOICEVALUE, CHOICEVALUE_METADATA } from './choice/choicevalue.js';
+export { CHOICELABEL, CHOICELABEL_METADATA } from './choice/choicelabel.js';
+export { HASOTHER, HASOTHER_METADATA } from './choice/hasother.js';
+export { OTHER, OTHER_METADATA } from './choice/other.js';
+export { CHOICEVALUES, CHOICEVALUES_METADATA } from './choice/choicevalues.js';
+export { CHOICELABELS, CHOICELABELS_METADATA } from './choice/choicelabels.js';
+export { FORM, FORM_METADATA } from './schema/form.js';
+export {
+  DATANAMES,
+  DATANAMES_METADATA,
+  __setDataNamesContext,
+  __clearDataNamesContext,
+} from './schema/datanames.js';
+export { ABS, ABS_METADATA } from './math/abs.js';
+export { CEILING, CEILING_METADATA } from './math/ceiling.js';
+export { COS, COS_METADATA } from './math/cos.js';
+export { SIN, SIN_METADATA } from './math/sin.js';
+export { ROUND, ROUND_METADATA } from './math/round.js';
+export { UPPER, UPPER_METADATA } from './string/upper.js';
 
-// Export event builtins
-export { ALERT } from './event/ui/alert.js';
-export { SETVALUE } from './event/field/setvalue.js';
-export { ON } from './event/control/on.js';
-export { OFF } from './event/control/off.js';
+export { ALERT, ALERT_METADATA } from './event/ui/alert.js';
+export { SETVALUE, SETVALUE_METADATA } from './event/field/setvalue.js';
+export { ON, ON_METADATA } from './event/control/on.js';
+export { OFF, OFF_METADATA } from './event/control/off.js';
 export { __consumeEventOperations } from './event/event-operations-collector.js';
 
-// Main builtins object for backward compatibility
-export const builtins = {
-  IF,
-  AND,
-  OR,
-  COUNT,
-  COUNTA,
-  COUNTBLANK,
-  ARRAY,
-  SETRESULT,
-  EVAL,
-  CHOICEVALUE,
-  CHOICELABEL,
-  HASOTHER,
-  OTHER,
-  CHOICEVALUES,
-  CHOICELABELS,
-  FORM, // Available in both calculations and events
-  DATANAMES,
-  ABS,
-  CEILING,
-  COS,
-  SIN,
-  ROUND,
-  UPPER,
-};
+const CALCULATION_AND_EVENT_ENTRIES = Object.freeze([
+  { implementation: IF, definition: IF_METADATA },
+  { implementation: AND, definition: AND_METADATA },
+  { implementation: OR, definition: OR_METADATA },
+  { implementation: COUNT, definition: COUNT_METADATA },
+  { implementation: COUNTA, definition: COUNTA_METADATA },
+  { implementation: COUNTBLANK, definition: COUNTBLANK_METADATA },
+  { implementation: ARRAY, definition: ARRAY_METADATA },
+  { implementation: SETRESULT, definition: SETRESULT_METADATA },
+  { implementation: EVAL, definition: EVAL_METADATA },
+  { implementation: CHOICEVALUE, definition: CHOICEVALUE_METADATA },
+  { implementation: CHOICELABEL, definition: CHOICELABEL_METADATA },
+  { implementation: HASOTHER, definition: HASOTHER_METADATA },
+  { implementation: OTHER, definition: OTHER_METADATA },
+  { implementation: CHOICEVALUES, definition: CHOICEVALUES_METADATA },
+  { implementation: CHOICELABELS, definition: CHOICELABELS_METADATA },
+  { implementation: FORM, definition: FORM_METADATA },
+  { implementation: DATANAMES, definition: DATANAMES_METADATA },
+  { implementation: ABS, definition: ABS_METADATA },
+  { implementation: CEILING, definition: CEILING_METADATA },
+  { implementation: COS, definition: COS_METADATA },
+  { implementation: SIN, definition: SIN_METADATA },
+  { implementation: ROUND, definition: ROUND_METADATA },
+  { implementation: UPPER, definition: UPPER_METADATA },
+]);
+
+const EVENT_ONLY_ENTRIES = Object.freeze([
+  { implementation: ALERT, definition: ALERT_METADATA },
+  { implementation: SETVALUE, definition: SETVALUE_METADATA },
+  { implementation: ON, definition: ON_METADATA },
+  { implementation: OFF, definition: OFF_METADATA },
+]);
+
+function buildBuiltinObject(entries) {
+  return Object.freeze(
+    Object.fromEntries(
+      entries.map(({ implementation, definition }) => [definition.name, implementation])
+    )
+  );
+}
+
+function filterDefinitionsByContext(definitions, context) {
+  return Object.freeze(definitions.filter((definition) => definition.contexts.includes(context)));
+}
+
+export const builtins = buildBuiltinObject(CALCULATION_AND_EVENT_ENTRIES);
+
+export const eventBuiltins = buildBuiltinObject(EVENT_ONLY_ENTRIES);
+
+export const BUILTIN_DEFINITIONS = Object.freeze(
+  [...CALCULATION_AND_EVENT_ENTRIES, ...EVENT_ONLY_ENTRIES].map(({ definition }) => definition)
+);
+
+export const CALCULATION_BUILTIN_DEFINITIONS = filterDefinitionsByContext(
+  BUILTIN_DEFINITIONS,
+  BUILTIN_CONTEXTS.CALCULATION
+);
+
+export const EVENT_BUILTIN_DEFINITIONS = filterDefinitionsByContext(
+  BUILTIN_DEFINITIONS,
+  BUILTIN_CONTEXTS.EVENT
+);
+
+export const BUILTIN_DEFINITION_BY_NAME = new Map(
+  BUILTIN_DEFINITIONS.map((definition) => [definition.name, definition])
+);
 
-// Event-specific builtins (only available in event context)
-export const eventBuiltins = {
-  ALERT,
-  SETVALUE,
-  ON,
-  OFF,
-  // Future: CONFIRM, NOTIFY, etc.
-};
+export function getBuiltinDefinitions() {
+  return BUILTIN_DEFINITIONS.map(cloneBuiltinMetadata);
+}

package/src/builtins/schema/datanames.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin DATANAMES
  * @description Returns the data names of form fields, optionally filtered by field type
@@ -13,6 +15,14 @@
  * // Get only TextField data names
  * DATANAMES('TextField')
  */
+export const DATANAMES_METADATA = defineBuiltinMetadata({
+  name: 'DATANAMES',
+  category: 'schema',
+  signature: "DATANAMES(type = 'any')",
+  description: 'Return form field data names, optionally filtered by field type.',
+  examples: ["DATANAMES('NumericField')"],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
 
 // Global schema context for DATANAMES() - set during expression evaluation
 let _dataNamesSchema = null;

package/src/builtins/schema/form.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin FORM
  * @description Access to the nested JSON form definition (future implementation)
@@ -12,6 +14,15 @@
  * // Check if form has RepeatableSections
  * FORM().elements.some(el => el.type === 'RepeatableSection')
  */
+export const FORM_METADATA = defineBuiltinMetadata({
+  name: 'FORM',
+  category: 'schema',
+  signature: 'FORM()',
+  description: 'Access the form definition. Reserved for a future implementation.',
+  examples: ['FORM()'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
 export function FORM() {
   // Placeholder for future implementation
   // Will provide access to nested JSON form definition

package/src/builtins/string/upper.js

@@ -1,3 +1,5 @@
+import { BUILTIN_CONTEXTS, defineBuiltinMetadata } from '../builtin-metadata.js';
+
 /**
  * @builtin UPPER
  * @description Returns the uppercase version of a string
@@ -13,9 +15,18 @@
  * // Returns "ABC123"
  * UPPER("abc123")
  */
+export const UPPER_METADATA = defineBuiltinMetadata({
+  name: 'UPPER',
+  category: 'string',
+  signature: 'UPPER(value)',
+  description: 'Convert a string to uppercase.',
+  examples: ['UPPER($city_name)'],
+  contexts: [BUILTIN_CONTEXTS.CALCULATION, BUILTIN_CONTEXTS.EVENT],
+});
+
 export const UPPER = (value) => {
   if (value == null) {
     return '';
   }
   return String(value).toUpperCase();
-};
+};

package/src/engine/context-resolver.js

@@ -66,25 +66,48 @@ export class ContextResolver {
   }
 
   /**
-   * Determine if a field is accessible from the current execution context
+   * Resolve field access with structured metadata for editor integrations.
    * @param {Object} executionContext - Current execution context
    * @param {string} fieldName - Field data_name being accessed
-   * @returns {string} 'accessible', 'restricted', or 'not_found'
+   * @param {Object | null} [providedFieldInfo]
+   * @returns {{
+   *   level: 'accessible' | 'restricted' | 'not_found',
+   *   code: 'main_form' | 'same_repeatable_section' | 'ancestor_repeatable_context' | 'different_repeatable_section' | null,
+   *   message: string | null,
+   *   suggestion: string | null,
+   *   fieldInfo: Object | null,
+   * }}
    */
-  resolveFieldAccess(executionContext, fieldName) {
-    const fieldInfo = this.fieldOwnership.get(fieldName);
+  resolveFieldAccessInfo(executionContext, fieldName, providedFieldInfo = null) {
+    const fieldInfo = providedFieldInfo || this.fieldOwnership.get(fieldName) || null;
 
     if (!fieldInfo) {
-      return 'not_found';
+      return {
+        level: 'not_found',
+        code: null,
+        message: `Field '${fieldName}' does not exist in the form schema`,
+        suggestion: `Check that field '${fieldName}' exists in the form schema`,
+        fieldInfo: null,
+      };
     }
 
     // Main form fields (no parent RepeatableSection) are always accessible
     if (fieldInfo.parentPath.length === 0) {
-      return 'accessible';
+      return this.buildAccessInfo('accessible', 'main_form', fieldName, fieldInfo, executionContext);
     }
 
     // RepeatableSection field access depends on execution context
-    return this.checkRepeatableSectionAccess(executionContext, fieldInfo);
+    return this.checkRepeatableSectionAccessInfo(executionContext, fieldName, fieldInfo);
+  }
+
+  /**
+   * Determine if a field is accessible from the current execution context
+   * @param {Object} executionContext - Current execution context
+   * @param {string} fieldName - Field data_name being accessed
+   * @returns {string} 'accessible', 'restricted', or 'not_found'
+   */
+  resolveFieldAccess(executionContext, fieldName) {
+    return this.resolveFieldAccessInfo(executionContext, fieldName).level;
   }
 
   /**
@@ -94,22 +117,49 @@ export class ContextResolver {
    * @returns {string} 'accessible' or 'restricted'
    */
   checkRepeatableSectionAccess(executionContext, fieldInfo) {
+    return this.checkRepeatableSectionAccessInfo(
+      executionContext,
+      fieldInfo.field?.data_name || fieldInfo.preferredKey,
+      fieldInfo
+    ).level;
+  }
+
+  /**
+   * Check RepeatableSection field access and return structured access metadata.
+   * @param {Object} executionContext - Current execution context
+   * @param {string} fieldName - Field data_name being accessed
+   * @param {Object} fieldInfo - Field ownership information
+   * @returns {{
+   *   level: 'accessible' | 'restricted' | 'not_found',
+   *   code: 'main_form' | 'same_repeatable_section' | 'ancestor_repeatable_context' | 'different_repeatable_section' | null,
+   *   message: string | null,
+   *   suggestion: string | null,
+   *   fieldInfo: Object | null,
+   * }}
+   */
+  checkRepeatableSectionAccessInfo(executionContext, fieldName, fieldInfo) {
     const { type: contextType, eventType, fieldName: contextFieldName } = executionContext;
 
     if (contextType === 'calculation') {
       // CalculatedField can only access fields in same RepeatableSection context
       const calculationFieldInfo = this.fieldOwnership.get(contextFieldName);
       if (!calculationFieldInfo) {
-        return 'restricted'; // Unknown calculation field
+        return this.buildAccessInfo(
+          'restricted',
+          'different_repeatable_section',
+          fieldName,
+          fieldInfo,
+          executionContext
+        );
       }
 
-      // Check if both fields have the same RepeatableSection ancestry
-      return this.haveSameRepeatableSectionContext(
+      return this.resolveRepeatableSectionRelationship(
         calculationFieldInfo.parentPath,
-        fieldInfo.parentPath
-      )
-        ? 'accessible'
-        : 'restricted';
+        fieldInfo.parentPath,
+        fieldName,
+        fieldInfo,
+        executionContext
+      );
     }
 
     if (contextType === 'event') {
@@ -118,38 +168,75 @@ export class ContextResolver {
       switch (eventInfo.scope) {
         case 'main':
           // Record events can't access RepeatableSection fields
-          return 'restricted';
+          return this.buildAccessInfo(
+            'restricted',
+            'different_repeatable_section',
+            fieldName,
+            fieldInfo,
+            executionContext
+          );
 
         case 'contextual':
           // Field events can access fields in same RepeatableSection context
           if (!contextFieldName) {
-            return 'restricted'; // No field context
+            return this.buildAccessInfo(
+              'restricted',
+              'different_repeatable_section',
+              fieldName,
+              fieldInfo,
+              executionContext
+            );
           }
 
           const triggerFieldInfo = this.fieldOwnership.get(contextFieldName);
           if (!triggerFieldInfo) {
-            return 'restricted'; // Unknown trigger field
+            return this.buildAccessInfo(
+              'restricted',
+              'different_repeatable_section',
+              fieldName,
+              fieldInfo,
+              executionContext
+            );
           }
 
-          return this.haveSameRepeatableSectionContext(
+          return this.resolveRepeatableSectionRelationship(
             triggerFieldInfo.parentPath,
-            fieldInfo.parentPath
-          )
-            ? 'accessible'
-            : 'restricted';
+            fieldInfo.parentPath,
+            fieldName,
+            fieldInfo,
+            executionContext
+          );
 
         case 'repeatable':
           // RepeatableSection events - future implementation
           // For now, assume accessible (will be refined when implemented)
-          return 'accessible';
+          return this.buildAccessInfo(
+            'accessible',
+            'same_repeatable_section',
+            fieldName,
+            fieldInfo,
+            executionContext
+          );
 
         default:
-          return 'restricted';
+          return this.buildAccessInfo(
+            'restricted',
+            'different_repeatable_section',
+            fieldName,
+            fieldInfo,
+            executionContext
+          );
       }
     }
 
     // Unknown context type
-    return 'restricted';
+    return this.buildAccessInfo(
+      'restricted',
+      'different_repeatable_section',
+      fieldName,
+      fieldInfo,
+      executionContext
+    );
   }
 
   /**
@@ -159,25 +246,80 @@ export class ContextResolver {
    * @returns {boolean} True if they share the same RepeatableSection context
    */
   haveSameRepeatableSectionContext(parentPath1, parentPath2) {
-    const contextPath = parentPath1;
-    const targetPath = parentPath2;
+    return this.resolveRepeatableSectionAccessCode(parentPath1, parentPath2) !== 'different_repeatable_section';
+  }
+
+  resolveRepeatableSectionRelationship(
+    contextPath,
+    targetPath,
+    fieldName,
+    fieldInfo,
+    executionContext
+  ) {
+    const code = this.resolveRepeatableSectionAccessCode(contextPath, targetPath);
+    const level = code === 'different_repeatable_section' ? 'restricted' : 'accessible';
+
+    return this.buildAccessInfo(level, code, fieldName, fieldInfo, executionContext);
+  }
 
-    // Main form calculations can only access other main form fields
-    if (contextPath.length === 0) {
-      return targetPath.length === 0;
+  resolveRepeatableSectionAccessCode(contextPath, targetPath) {
+    if (targetPath.length === 0) {
+      return 'main_form';
     }
 
-    // Child context can access its own fields
     if (ContextResolver.pathsEqual(contextPath, targetPath)) {
-      return true;
+      return contextPath.length === 0 ? 'main_form' : 'same_repeatable_section';
     }
 
-    // Child context can access ancestors (including main form)
     if (targetPath.length < contextPath.length && ContextResolver.isPrefix(targetPath, contextPath)) {
-      return true;
+      return targetPath.length === 0 ? 'main_form' : 'ancestor_repeatable_context';
+    }
+
+    return 'different_repeatable_section';
+  }
+
+  buildAccessInfo(level, code, fieldName, fieldInfo, executionContext) {
+    if (level === 'accessible') {
+      return {
+        level,
+        code,
+        message: null,
+        suggestion: null,
+        fieldInfo,
+      };
+    }
+
+    return {
+      level,
+      code,
+      message: `Field '${fieldName}' is not accessible from current context`,
+      suggestion: this.buildRestrictedAccessSuggestion(executionContext, fieldName, fieldInfo, code),
+      fieldInfo,
+    };
+  }
+
+  buildRestrictedAccessSuggestion(executionContext, fieldName, fieldInfo, code) {
+    const { type: contextType, eventType } = executionContext;
+
+    if (contextType === 'calculation') {
+      if (code === 'different_repeatable_section') {
+        return `CalculatedField can only access fields in the same RepeatableSection or ancestor contexts. Field '${fieldName}' is in RepeatableSection: ${fieldInfo.parentPath.join(' -> ')}`;
+      }
     }
 
-    return false;
+    if (contextType === 'event') {
+      const eventInfo = getEventInfo(eventType);
+
+      if (eventInfo.scope === 'main') {
+        return `Record-level events (like '${eventType}') can only access main form fields, not RepeatableSection fields`;
+      }
+
+      if (eventInfo.scope === 'contextual') {
+        return `Field events can only access fields in the same RepeatableSection or ancestor contexts as the triggering field`;
+      }
+    }
+
+    return 'Check the field access rules for your current context';
   }
 
   static isPrefix(prefix, fullPath) {
@@ -221,19 +363,25 @@ export class ContextResolver {
    * @returns {Object} Warning object with structured information
    */
   generateAccessWarning(executionContext, fieldName, reason) {
-    const fieldInfo = this.fieldOwnership.get(fieldName);
-    const suggestion = this.generateAccessSuggestion(executionContext, fieldName, fieldInfo);
+    const accessInfo =
+      reason === 'not_found'
+        ? this.resolveFieldAccessInfo(executionContext, fieldName)
+        : this.resolveFieldAccessInfo(executionContext, fieldName);
+    const fieldInfo = accessInfo.fieldInfo;
 
     return {
       type: 'FIELD_ACCESS_WARNING',
       fieldName,
       executionContext,
       reason,
+      accessCode: accessInfo.code,
       message:
-        reason === 'not_found'
+        accessInfo.message ||
+        (reason === 'not_found'
           ? `Field '${fieldName}' does not exist in the form schema`
-          : `Field '${fieldName}' is not accessible from current context`,
-      suggestion,
+          : `Field '${fieldName}' is not accessible from current context`),
+      suggestion:
+        accessInfo.suggestion || this.generateAccessSuggestion(executionContext, fieldName, fieldInfo),
       fieldContext: fieldInfo
         ? {
             parentPath: fieldInfo.parentPath,
@@ -252,28 +400,26 @@ export class ContextResolver {
    * @returns {string} Helpful suggestion message
    */
   generateAccessSuggestion(executionContext, fieldName, fieldInfo) {
-    if (!fieldInfo) {
-      return `Check that field '${fieldName}' exists in the form schema`;
+    const accessInfo = this.resolveFieldAccessInfo(executionContext, fieldName, fieldInfo);
+
+    if (accessInfo.suggestion) {
+      return accessInfo.suggestion;
     }
 
-    const { type: contextType, eventType, fieldName: contextFieldName } = executionContext;
+    if (accessInfo.level === 'not_found') {
+      return `Check that field '${fieldName}' exists in the form schema`;
+    }
 
-    if (contextType === 'calculation') {
-      if (fieldInfo.parentPath.length === 0) {
-        return 'Main form fields are always accessible from calculations';
-      } else {
-        return `CalculatedField can only access fields in the same RepeatableSection. Field '${fieldName}' is in RepeatableSection: ${fieldInfo.parentPath.join(' -> ')}`;
-      }
+    if (accessInfo.code === 'main_form') {
+      return 'Main form fields are always accessible from calculations';
     }
 
-    if (contextType === 'event') {
-      const eventInfo = getEventInfo(eventType);
+    if (accessInfo.code === 'same_repeatable_section') {
+      return 'Fields in the same RepeatableSection are accessible from this context';
+    }
 
-      if (eventInfo.scope === 'main') {
-        return `Record-level events (like '${eventType}') can only access main form fields, not RepeatableSection fields`;
-      } else if (eventInfo.scope === 'contextual') {
-        return `Field events can only access fields in the same RepeatableSection context as the triggering field`;
-      }
+    if (accessInfo.code === 'ancestor_repeatable_context') {
+      return 'Fields in ancestor RepeatableSection contexts are accessible from this context';
     }
 
     return 'Check the field access rules for your current context';