form0-core 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form0-core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },

package/src/engine/calculation.js

@@ -1,7 +1,12 @@
 import { runExpression } from './evaluator.js';
-import { flattenFields } from '../utilities/field-helpers.js';
 import { ContextResolver } from './context-resolver.js';
 import { WarningSystem } from './warning-system.js';
+import {
+  buildCalculationDependencyPlan,
+  buildCalculationExecutionContext,
+  extractStaticFieldReferences,
+} from '../utilities/calculation-dependencies.js';
+import { areStructuredValuesEqual } from '../utilities/value-equality.js';
 
 export function evaluateCalculatedFields(
   schema,
@@ -10,69 +15,68 @@ export function evaluateCalculatedFields(
   securityConfig,
   contextResolver = null,
   warningSystem = null,
-  runtimeDiagnostics = null
+  runtimeDiagnostics = null,
+  calculationPlan = null
 ) {
-  const fields = flattenFields(schema.elements);
-
-  // Initialize context resolver and warning system if not provided (backward compatibility)
   const resolver = contextResolver || new ContextResolver(schema);
   const warnings = warningSystem || new WarningSystem();
+  const plan = calculationPlan || buildCalculationDependencyPlan(schema, resolver);
 
-  fields.forEach((field) => {
-    if (field.type === 'CalculatedField' && field.calculate) {
-      try {
-        // Create execution context for this calculation
-        const executionContext = {
-          type: 'calculation',
-          fieldName: field.data_name,
-          parentPath: resolver.getFieldInfo(field.data_name)?.parentPath || [],
-        };
-
-        const context = buildScopedContext(
-          values,
-          helpers,
-          executionContext,
-          resolver,
-          warnings,
-          field.calculate
-        );
-        values[field.data_name] = runExpression(
-          field.calculate,
-          context,
-          securityConfig,
-          false,
-          schema,
-          {
-            suppressConsoleWarning: Array.isArray(runtimeDiagnostics),
-            onError: (error) => {
-              if (!Array.isArray(runtimeDiagnostics)) {
-                return;
-              }
-
-              runtimeDiagnostics.push({
-                fieldName: field.data_name,
-                message:
-                  error instanceof Error && error.message
-                    ? error.message
-                    : 'Unknown calculation runtime error.',
-              });
-            },
-          }
-        );
-      } catch (e) {
-        if (Array.isArray(runtimeDiagnostics)) {
-          runtimeDiagnostics.push({
-            fieldName: field.data_name,
-            message:
-              e instanceof Error && e.message
-                ? e.message
-                : 'Unknown calculation runtime error.',
-          });
-        }
-        if (!Array.isArray(runtimeDiagnostics)) {
-          console.warn(`Calculation failed for ${field.data_name}:`, e.message);
-        }
-      }
+  emitDependencyPlanWarnings(plan, warnings, runtimeDiagnostics);
+
+  if (plan.totalCalculatedFieldCount === 0) {
+    return;
+  }
+
+  if (plan.hasDynamicDependencies) {
+    evaluateFieldSequenceUntilStable(
+      plan.orderedFieldNames,
+      plan,
+      schema,
+      values,
+      helpers,
+      securityConfig,
+      resolver,
+      warnings,
+      runtimeDiagnostics
+    );
+    return;
+  }
+
+  plan.orderedComponentIds.forEach((componentId) => {
+    const component = plan.componentsById.get(componentId);
+    if (!component || component.fieldNames.length === 0) {
+      return;
+    }
+
+    if (component.isCyclic) {
+      evaluateFieldSequenceUntilStable(
+        component.fieldNames,
+        plan,
+        schema,
+        values,
+        helpers,
+        securityConfig,
+        resolver,
+        warnings,
+        runtimeDiagnostics
+      );
+      return;
+    }
+
+    const fieldName = component.fieldNames[0];
+    const node = plan.nodesByDataName.get(fieldName);
+    if (node?.field) {
+      evaluateCalculatedField(
+        node.field,
+        schema,
+        values,
+        helpers,
+        securityConfig,
+        resolver,
+        warnings,
+        runtimeDiagnostics
+      );
     }
   });
 }
@@ -87,43 +91,32 @@ function buildScopedContext(
 ) {
   const ctx = { ...helpers };
 
-  // Find which fields are actually referenced in the expression
-  const referencedFields = extractFieldReferences(expressionCode);
-
-  // Track problematic fields that are actually accessed
+  const referencedFields = extractStaticFieldReferences(expressionCode);
   const restrictedAccessedFields = [];
   const notFoundAccessedFields = [];
 
-  // Add scoped field access
   for (const [fieldName, value] of Object.entries(values)) {
     const accessLevel = contextResolver.resolveFieldAccess(executionContext, fieldName);
 
     if (accessLevel === 'accessible') {
       ctx[`$${fieldName}`] = value;
     } else if (accessLevel === 'restricted') {
-      // Only add restricted fields to context if they're actually referenced
       if (referencedFields.has(fieldName)) {
         ctx[`$${fieldName}`] = undefined;
         restrictedAccessedFields.push(fieldName);
       }
-      // If not referenced, don't add to context at all
     }
-    // 'not_found' fields are not added to context at all
   }
 
-  // Check for not_found fields that are actually referenced
   for (const fieldName of referencedFields) {
-    // Check if this field was processed above (exists in values)
     if (!(fieldName in values)) {
       const accessLevel = contextResolver.resolveFieldAccess(executionContext, fieldName);
       if (accessLevel === 'not_found') {
         notFoundAccessedFields.push(fieldName);
-        // Don't add to context - it will be undefined when accessed
       }
     }
   }
 
-  // Emit warnings for restricted fields that are actually accessed
   restrictedAccessedFields.forEach((fieldName) => {
     const warning = contextResolver.generateAccessWarning(
       executionContext,
@@ -133,7 +126,6 @@ function buildScopedContext(
     warningSystem.emitWarning(warning);
   });
 
-  // Emit warnings for not_found fields that are actually accessed
   notFoundAccessedFields.forEach((fieldName) => {
     const warning = contextResolver.generateAccessWarning(executionContext, fieldName, 'not_found');
     warningSystem.emitWarning(warning);
@@ -142,93 +134,225 @@ function buildScopedContext(
   return ctx;
 }
 
-/**
- * Extract field references from expression code (simple regex-based approach)
- * Skips field references inside EVAL() calls to avoid false positives from dynamic field construction
- * @param {string} code - The expression/code to analyze
- * @returns {Set<string>} Set of field names referenced in the code
- */
-function extractFieldReferences(code) {
-  const fieldReferences = new Set();
-
-  // Remove content inside EVAL() calls to avoid false positives
-  // This handles complex patterns like EVAL('string' + variable + 'more')
-  const cleanedCode = removeEvalContents(code);
-
-  // Simple regex to find $fieldname patterns in the cleaned code
-  // This matches $ followed by valid JavaScript identifier characters
-  const fieldRegex = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
-  let match;
-
-  while ((match = fieldRegex.exec(cleanedCode)) !== null) {
-    fieldReferences.add(match[1]); // Add the field name (without $)
+function pushRuntimeDiagnostic(
+  runtimeDiagnostics,
+  fieldName,
+  message,
+  severity = 'error',
+  dedupeKey = null
+) {
+  if (!Array.isArray(runtimeDiagnostics)) {
+    return;
   }
 
-  return fieldReferences;
+  if (
+    dedupeKey &&
+    runtimeDiagnostics.some(
+      (diagnostic) =>
+        diagnostic?.fieldName === fieldName &&
+        diagnostic?.message === message &&
+        diagnostic?.dedupeKey === dedupeKey
+    )
+  ) {
+    return;
+  }
+
+  runtimeDiagnostics.push({
+    fieldName,
+    message,
+    severity,
+    dedupeKey,
+  });
 }
 
-/**
- * Remove EVAL() function calls and their contents from code
- * Handles nested parentheses and complex expressions inside EVAL()
- * @param {string} code - The code to clean
- * @returns {string} Code with EVAL() contents removed
- */
-function removeEvalContents(code) {
-  let result = '';
-  let i = 0;
-
-  while (i < code.length) {
-    // Look for EVAL pattern
-    const evalMatch = code.substring(i).match(/^EVAL\s*\(/);
-    if (evalMatch) {
-      // Found EVAL(, add "EVAL()" to result and skip the entire call
-      result += 'EVAL()';
-      i += evalMatch[0].length;
-
-      // Skip everything until we find the matching closing parenthesis
-      let parenCount = 1;
-      let inSingleQuote = false;
-      let inDoubleQuote = false;
-      let inBacktick = false;
-
-      while (i < code.length && parenCount > 0) {
-        const char = code[i];
-
-        // Handle string literals (ignore parentheses inside strings)
-        if (char === "'" && !inDoubleQuote && !inBacktick) {
-          inSingleQuote = !inSingleQuote;
-        } else if (char === '"' && !inSingleQuote && !inBacktick) {
-          inDoubleQuote = !inDoubleQuote;
-        } else if (char === '`' && !inSingleQuote && !inDoubleQuote) {
-          inBacktick = !inBacktick;
-        }
-
-        // Only count parentheses when not inside strings
-        if (!inSingleQuote && !inDoubleQuote && !inBacktick) {
-          if (char === '(') {
-            parenCount++;
-          } else if (char === ')') {
-            parenCount--;
-          }
-        }
-
-        i++;
-      }
-    } else {
-      // Not an EVAL call, add character to result
-      result += code[i];
-      i++;
+function emitDependencyPlanWarnings(plan, warningSystem, runtimeDiagnostics) {
+  plan.dynamicFieldNames.forEach((fieldName) => {
+    const message = `CalculatedField '${fieldName}' uses dynamic field access. Runtime evaluation falls back to bounded stabilization.`;
+    warningSystem.emitWarning({
+      type: 'calculation_dependency',
+      reason: 'dynamic_dependencies',
+      message,
+      suggestion: 'Prefer direct $field references when possible to enable dependency ordering.',
+      executionContext: {
+        type: 'calculation',
+        fieldName,
+      },
+      fieldContext: {
+        fieldName,
+        dynamic: true,
+      },
+    });
+    pushRuntimeDiagnostic(
+      runtimeDiagnostics,
+      fieldName,
+      message,
+      'warning',
+      `dynamic:${fieldName}`
+    );
+  });
+
+  plan.cyclicComponentIds.forEach((componentId) => {
+    const component = plan.componentsById.get(componentId);
+    if (!component?.isCyclic) {
+      return;
     }
+
+    const fieldNames = component.fieldNames;
+    const message = `CalculatedField dependency cycle detected: ${fieldNames.join(' -> ')}. Runtime evaluation will use bounded stabilization.`;
+    warningSystem.emitWarning({
+      type: 'calculation_dependency',
+      reason: 'cyclic_dependencies',
+      message,
+      suggestion:
+        'Remove the cycle or break it with a source field so calculated values can be evaluated deterministically.',
+      executionContext: {
+        type: 'calculation',
+        fieldName: fieldNames[0] || null,
+      },
+      fieldContext: {
+        fieldNames: [...fieldNames],
+        cyclic: true,
+      },
+    });
+
+    fieldNames.forEach((fieldName) => {
+      pushRuntimeDiagnostic(
+        runtimeDiagnostics,
+        fieldName,
+        message,
+        'warning',
+        `cycle:${componentId}`
+      );
+    });
+  });
+}
+
+function evaluateCalculatedField(
+  field,
+  schema,
+  values,
+  helpers,
+  securityConfig,
+  resolver,
+  warnings,
+  runtimeDiagnostics
+) {
+  if (!field?.data_name || !field.calculate) {
+    return { changed: false, hasError: false };
   }
 
-  return result;
+  try {
+    const executionContext = buildCalculationExecutionContext(schema, field.data_name, resolver);
+    const context = buildScopedContext(
+      values,
+      helpers,
+      executionContext,
+      resolver,
+      warnings,
+      field.calculate
+    );
+    const previousValue = values[field.data_name];
+    const nextValue = runExpression(field.calculate, context, securityConfig, false, schema, {
+      suppressConsoleWarning: Array.isArray(runtimeDiagnostics),
+      onError: (error) => {
+        pushRuntimeDiagnostic(
+          runtimeDiagnostics,
+          field.data_name,
+          error instanceof Error && error.message
+            ? error.message
+            : 'Unknown calculation runtime error.'
+        );
+      },
+    });
+    values[field.data_name] = nextValue;
+
+    return {
+      changed: !areStructuredValuesEqual(previousValue, nextValue),
+      hasError: false,
+    };
+  } catch (error) {
+    pushRuntimeDiagnostic(
+      runtimeDiagnostics,
+      field.data_name,
+      error instanceof Error && error.message ? error.message : 'Unknown calculation runtime error.'
+    );
+
+    if (!Array.isArray(runtimeDiagnostics)) {
+      console.warn(`Calculation failed for ${field.data_name}:`, error?.message);
+    }
+
+    return { changed: false, hasError: true };
+  }
 }
 
-// Legacy function for backward compatibility
-function buildContext(values, helpers) {
-  const ctx = {};
-  for (const key in values) {
-    ctx[`$${key}`] = values[key];
+function evaluateFieldSequenceUntilStable(
+  fieldNames,
+  plan,
+  schema,
+  values,
+  helpers,
+  securityConfig,
+  resolver,
+  warnings,
+  runtimeDiagnostics
+) {
+  const maxPasses = Math.max(2, plan.totalCalculatedFieldCount);
+  let stillChangingFieldNames = [];
+
+  for (let pass = 0; pass < maxPasses; pass += 1) {
+    stillChangingFieldNames = [];
+
+    fieldNames.forEach((fieldName) => {
+      const node = plan.nodesByDataName.get(fieldName);
+      if (!node?.field) {
+        return;
+      }
+
+      const result = evaluateCalculatedField(
+        node.field,
+        schema,
+        values,
+        helpers,
+        securityConfig,
+        resolver,
+        warnings,
+        runtimeDiagnostics
+      );
+
+      if (result.changed) {
+        stillChangingFieldNames.push(fieldName);
+      }
+    });
+
+    if (stillChangingFieldNames.length === 0) {
+      return;
+    }
   }
-  return { ...ctx, ...helpers };
+
+  const message = `Calculated fields did not stabilize within ${maxPasses} evaluation passes: ${stillChangingFieldNames.join(', ')}.`;
+  warnings.emitWarning({
+    type: 'calculation_dependency',
+    reason: 'non_converging_runtime',
+    message,
+    suggestion:
+      'Review the involved CalculatedField expressions for dependency cycles or dynamic references that never settle.',
+    executionContext: {
+      type: 'calculation',
+      fieldName: stillChangingFieldNames[0] || null,
+    },
+    fieldContext: {
+      fieldNames: [...stillChangingFieldNames],
+      maxPasses,
+    },
+  });
+
+  stillChangingFieldNames.forEach((fieldName) => {
+    pushRuntimeDiagnostic(
+      runtimeDiagnostics,
+      fieldName,
+      message,
+      'warning',
+      `non-converging:${fieldNames.join(',')}`
+    );
+  });
 }

package/src/engine/form-engine.js

@@ -12,6 +12,7 @@ import { FIELD_SPECS } from '../schema/field-specs.js';
 import { ContextResolver } from './context-resolver.js';
 import { WarningSystem } from './warning-system.js';
 import { expandBuildingPlanSchema } from '../schema/building-plan-expander.js';
+import { buildCalculationDependencyPlan } from '../utilities/calculation-dependencies.js';
 
 export function createFormEngine({
   schema,
@@ -94,6 +95,7 @@ export function createFormEngine({
 
   // Initialize context resolution system
   const contextResolver = new ContextResolver(form);
+  const calculationPlan = buildCalculationDependencyPlan(form, contextResolver);
   const sharedWarningSystem = warningSystem || new WarningSystem();
 
   // Initialize event system with context resolution
@@ -128,7 +130,8 @@ export function createFormEngine({
       security,
       contextResolver,
       sharedWarningSystem,
-      runtimeDiagnostics
+      runtimeDiagnostics,
+      calculationPlan
     );
     evaluateRequirement(form, values, required);
     evaluateVisibility(form, values, visible);

package/src/utilities/calculation-dependencies.js

@@ -0,0 +1,311 @@
+import { ContextResolver } from '../engine/context-resolver.js';
+import { flattenFields } from './field-helpers.js';
+
+function sortFieldNames(fieldNames, orderByFieldName) {
+  return [...fieldNames].sort(
+    (left, right) => orderByFieldName.get(left) - orderByFieldName.get(right)
+  );
+}
+
+function buildStronglyConnectedComponents(nodesByDataName, orderByFieldName) {
+  const indices = new Map();
+  const lowLinks = new Map();
+  const stack = [];
+  const onStack = new Set();
+  const components = [];
+  let currentIndex = 0;
+
+  function strongConnect(fieldName) {
+    indices.set(fieldName, currentIndex);
+    lowLinks.set(fieldName, currentIndex);
+    currentIndex += 1;
+    stack.push(fieldName);
+    onStack.add(fieldName);
+
+    const node = nodesByDataName.get(fieldName);
+    if (node) {
+      for (const dependency of node.dependencies) {
+        if (!indices.has(dependency)) {
+          strongConnect(dependency);
+          lowLinks.set(fieldName, Math.min(lowLinks.get(fieldName), lowLinks.get(dependency)));
+        } else if (onStack.has(dependency)) {
+          lowLinks.set(fieldName, Math.min(lowLinks.get(fieldName), indices.get(dependency)));
+        }
+      }
+    }
+
+    if (lowLinks.get(fieldName) !== indices.get(fieldName)) {
+      return;
+    }
+
+    const componentFieldNames = [];
+    while (stack.length > 0) {
+      const stackFieldName = stack.pop();
+      onStack.delete(stackFieldName);
+      componentFieldNames.push(stackFieldName);
+      if (stackFieldName === fieldName) {
+        break;
+      }
+    }
+
+    components.push(sortFieldNames(componentFieldNames, orderByFieldName));
+  }
+
+  const sortedFieldNames = sortFieldNames(nodesByDataName.keys(), orderByFieldName);
+  sortedFieldNames.forEach((fieldName) => {
+    if (!indices.has(fieldName)) {
+      strongConnect(fieldName);
+    }
+  });
+
+  return components;
+}
+
+function topologicallyOrderComponents(componentIds, componentEdges) {
+  const inDegree = new Map(componentIds.map((componentId) => [componentId, 0]));
+
+  componentEdges.forEach((targets) => {
+    targets.forEach((targetId) => {
+      inDegree.set(targetId, (inDegree.get(targetId) || 0) + 1);
+    });
+  });
+
+  const queue = componentIds.filter((componentId) => (inDegree.get(componentId) || 0) === 0);
+  const ordered = [];
+
+  while (queue.length > 0) {
+    const componentId = queue.shift();
+    ordered.push(componentId);
+
+    for (const targetId of componentEdges.get(componentId) || []) {
+      const nextDegree = (inDegree.get(targetId) || 0) - 1;
+      inDegree.set(targetId, nextDegree);
+      if (nextDegree === 0) {
+        queue.push(targetId);
+      }
+    }
+  }
+
+  if (ordered.length === componentIds.length) {
+    return ordered;
+  }
+
+  return [...componentIds];
+}
+
+export function normalizeCalculationFormSchema(schema) {
+  if (schema && Array.isArray(schema.elements)) {
+    return schema;
+  }
+
+  if (schema && schema.form && Array.isArray(schema.form.elements)) {
+    return schema.form;
+  }
+
+  throw new Error('Expected a form schema or a root schema containing form.elements');
+}
+
+export function hasDynamicCalculationDependencies(code) {
+  return /\bEVAL\s*\(/.test(typeof code === 'string' ? code : '');
+}
+
+export function removeEvalContents(code) {
+  const source = typeof code === 'string' ? code : '';
+  let result = '';
+  let i = 0;
+
+  while (i < source.length) {
+    const evalMatch = source.substring(i).match(/^EVAL\s*\(/);
+    if (evalMatch) {
+      result += 'EVAL()';
+      i += evalMatch[0].length;
+
+      let parenCount = 1;
+      let inSingleQuote = false;
+      let inDoubleQuote = false;
+      let inBacktick = false;
+
+      while (i < source.length && parenCount > 0) {
+        const char = source[i];
+
+        if (char === "'" && !inDoubleQuote && !inBacktick) {
+          inSingleQuote = !inSingleQuote;
+        } else if (char === '"' && !inSingleQuote && !inBacktick) {
+          inDoubleQuote = !inDoubleQuote;
+        } else if (char === '`' && !inSingleQuote && !inDoubleQuote) {
+          inBacktick = !inBacktick;
+        }
+
+        if (!inSingleQuote && !inDoubleQuote && !inBacktick) {
+          if (char === '(') {
+            parenCount += 1;
+          } else if (char === ')') {
+            parenCount -= 1;
+          }
+        }
+
+        i += 1;
+      }
+    } else {
+      result += source[i];
+      i += 1;
+    }
+  }
+
+  return result;
+}
+
+export function extractStaticFieldReferenceMatches(code) {
+  const cleanedCode = removeEvalContents(code);
+  const fieldRegex = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
+  const matches = [];
+  let match;
+
+  while ((match = fieldRegex.exec(cleanedCode)) !== null) {
+    matches.push({
+      fieldName: match[1],
+      reference: `$${match[1]}`,
+      index: match.index,
+      length: match[0].length,
+    });
+  }
+
+  return matches;
+}
+
+export function extractStaticFieldReferences(code) {
+  return new Set(extractStaticFieldReferenceMatches(code).map((match) => match.fieldName));
+}
+
+export function buildCalculationExecutionContext(form, fieldDataName, resolver) {
+  return {
+    type: 'calculation',
+    fieldName: fieldDataName,
+    parentPath: resolver.getFieldInfo(fieldDataName)?.parentPath || [],
+  };
+}
+
+export function buildCalculationDependencyPlan(schema, contextResolver = null) {
+  const form = normalizeCalculationFormSchema(schema);
+  const resolver = contextResolver || new ContextResolver(form);
+  const fields = flattenFields(form.elements).filter((field) => field && typeof field === 'object');
+  const fieldsByDataName = new Map(
+    fields
+      .filter((field) => typeof field.data_name === 'string' && field.data_name.length > 0)
+      .map((field) => [field.data_name, field])
+  );
+
+  const orderByFieldName = new Map();
+  fields.forEach((field, index) => {
+    if (typeof field?.data_name === 'string') {
+      orderByFieldName.set(field.data_name, index);
+    }
+  });
+
+  const nodesByDataName = new Map();
+  fields.forEach((field) => {
+    if (field.type !== 'CalculatedField' || typeof field.data_name !== 'string') {
+      return;
+    }
+
+    const fieldName = field.data_name;
+    const executionContext = buildCalculationExecutionContext(form, fieldName, resolver);
+    const directReferences = extractStaticFieldReferences(field.calculate || '');
+    const dependencies = new Set();
+
+    directReferences.forEach((referenceFieldName) => {
+      const accessInfo = resolver.resolveFieldAccessInfo(executionContext, referenceFieldName);
+      if (accessInfo.level !== 'accessible') {
+        return;
+      }
+
+      const dependencyField = fieldsByDataName.get(referenceFieldName);
+      if (dependencyField?.type === 'CalculatedField') {
+        dependencies.add(referenceFieldName);
+      }
+    });
+
+    nodesByDataName.set(fieldName, {
+      field,
+      fieldName,
+      dependencies,
+      directReferences,
+      hasDynamicDependencies: hasDynamicCalculationDependencies(field.calculate || ''),
+    });
+  });
+
+  const componentFieldGroups = buildStronglyConnectedComponents(nodesByDataName, orderByFieldName);
+  const componentIdByFieldName = new Map();
+  const componentsById = new Map();
+
+  componentFieldGroups.forEach((fieldNames, componentIndex) => {
+    const componentId = `component_${componentIndex}`;
+    fieldNames.forEach((fieldName) => {
+      componentIdByFieldName.set(fieldName, componentId);
+    });
+    componentsById.set(componentId, {
+      id: componentId,
+      fieldNames,
+      hasDynamicDependencies: false,
+      isCyclic: false,
+    });
+  });
+
+  nodesByDataName.forEach((node) => {
+    node.componentId = componentIdByFieldName.get(node.fieldName);
+  });
+
+  componentsById.forEach((component) => {
+    component.hasDynamicDependencies = component.fieldNames.some(
+      (fieldName) => nodesByDataName.get(fieldName)?.hasDynamicDependencies
+    );
+    component.isCyclic =
+      component.fieldNames.length > 1 ||
+      component.fieldNames.some((fieldName) =>
+        nodesByDataName.get(fieldName)?.dependencies.has(fieldName)
+      );
+  });
+
+  const componentEdges = new Map(
+    Array.from(componentsById.keys(), (componentId) => [componentId, new Set()])
+  );
+
+  nodesByDataName.forEach((node) => {
+    const targetComponentId = node.componentId;
+    node.dependencies.forEach((dependencyFieldName) => {
+      const dependencyComponentId = componentIdByFieldName.get(dependencyFieldName);
+      if (!dependencyComponentId || dependencyComponentId === targetComponentId) {
+        return;
+      }
+      componentEdges.get(dependencyComponentId).add(targetComponentId);
+    });
+  });
+
+  const orderedComponentIds = topologicallyOrderComponents(
+    Array.from(componentsById.keys()),
+    componentEdges
+  );
+  const orderedFieldNames = orderedComponentIds.flatMap(
+    (componentId) => componentsById.get(componentId)?.fieldNames || []
+  );
+  const dynamicFieldNames = orderedFieldNames.filter(
+    (fieldName) => nodesByDataName.get(fieldName)?.hasDynamicDependencies
+  );
+  const cyclicComponentIds = orderedComponentIds.filter(
+    (componentId) => componentsById.get(componentId)?.isCyclic
+  );
+
+  return {
+    form,
+    fieldsByDataName,
+    nodesByDataName,
+    componentsById,
+    componentIdByFieldName,
+    orderedComponentIds,
+    orderedFieldNames,
+    hasDynamicDependencies: dynamicFieldNames.length > 0,
+    dynamicFieldNames,
+    cyclicComponentIds,
+    totalCalculatedFieldCount: orderedFieldNames.length,
+  };
+}

package/src/utilities/calculation-editor.js

@@ -8,6 +8,13 @@ import { createFormEngine } from '../engine/form-engine.js';
 import { WarningSystem } from '../engine/warning-system.js';
 import { DEFAULT_SECURITY_CONFIG } from '../security/config.js';
 import { validateExpression } from '../security/validation.js';
+import {
+  buildCalculationDependencyPlan,
+  buildCalculationExecutionContext,
+  extractStaticFieldReferenceMatches,
+  hasDynamicCalculationDependencies,
+  normalizeCalculationFormSchema,
+} from './calculation-dependencies.js';
 import {
   isMultilineCalculationExpression,
   normalizeInlineCalculationExpression,
@@ -53,67 +60,10 @@ const CALCULATION_BUILTIN_METADATA_BY_NAME = new Map(
   CALCULATION_BUILTIN_CATALOG.map((definition) => [definition.name, definition])
 );
 
-function normalizeFormSchema(schema) {
-  if (schema && Array.isArray(schema.elements)) {
-    return schema;
-  }
-
-  if (schema && schema.form && Array.isArray(schema.form.elements)) {
-    return schema.form;
-  }
-
-  throw new Error('Expected a form schema or a root schema containing form.elements');
-}
-
 function isBuiltinCallMatchAllowed(functionName) {
   return COMMON_GLOBAL_FUNCTIONS.has(functionName);
 }
 
-function removeEvalContents(code) {
-  let result = '';
-  let i = 0;
-
-  while (i < code.length) {
-    const evalMatch = code.substring(i).match(/^EVAL\s*\(/);
-    if (evalMatch) {
-      result += 'EVAL()';
-      i += evalMatch[0].length;
-
-      let parenCount = 1;
-      let inSingleQuote = false;
-      let inDoubleQuote = false;
-      let inBacktick = false;
-
-      while (i < code.length && parenCount > 0) {
-        const char = code[i];
-
-        if (char === "'" && !inDoubleQuote && !inBacktick) {
-          inSingleQuote = !inSingleQuote;
-        } else if (char === '"' && !inSingleQuote && !inBacktick) {
-          inDoubleQuote = !inDoubleQuote;
-        } else if (char === '`' && !inSingleQuote && !inDoubleQuote) {
-          inBacktick = !inBacktick;
-        }
-
-        if (!inSingleQuote && !inDoubleQuote && !inBacktick) {
-          if (char === '(') {
-            parenCount++;
-          } else if (char === ')') {
-            parenCount--;
-          }
-        }
-
-        i++;
-      }
-    } else {
-      result += code[i];
-      i++;
-    }
-  }
-
-  return result;
-}
-
 function extractFunctionCalls(code) {
   const functionCallPattern = /\b([A-Z_][A-Z0-9_]*)\s*\(/g;
   const matches = [];
@@ -130,32 +80,6 @@ function extractFunctionCalls(code) {
   return matches;
 }
 
-function extractFieldReferenceMatches(code) {
-  const cleanedCode = removeEvalContents(code);
-  const fieldRegex = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
-  const matches = [];
-  let match;
-
-  while ((match = fieldRegex.exec(cleanedCode)) !== null) {
-    matches.push({
-      fieldName: match[1],
-      reference: `$${match[1]}`,
-      index: match.index,
-      length: match[0].length,
-    });
-  }
-
-  return matches;
-}
-
-function buildExecutionContext(form, fieldDataName, resolver) {
-  return {
-    type: 'calculation',
-    fieldName: fieldDataName,
-    parentPath: resolver.getFieldInfo(fieldDataName)?.parentPath || [],
-  };
-}
-
 function cloneCatalogDefinition(definition) {
   return {
     ...definition,
@@ -254,7 +178,7 @@ function cloneSimulationSchema(schema) {
   }
 
   return {
-    form: deepClone(normalizeFormSchema(schema)),
+    form: deepClone(normalizeCalculationFormSchema(schema)),
   };
 }
 
@@ -383,9 +307,9 @@ export function getCalculationReferenceCatalog({
   fieldDataName,
   includeRestricted = false,
 }) {
-  const form = normalizeFormSchema(schema);
+  const form = normalizeCalculationFormSchema(schema);
   const resolver = new ContextResolver(form);
-  const executionContext = buildExecutionContext(form, fieldDataName, resolver);
+  const executionContext = buildCalculationExecutionContext(form, fieldDataName, resolver);
 
   return flattenFields(form.elements)
     .filter((field) => field && typeof field === 'object')
@@ -431,9 +355,14 @@ export function analyzeCalculationExpression({
   const setResultCalls = [];
 
   const normalizedExpression = typeof expression === 'string' ? expression : '';
-  const form = normalizeFormSchema(schema);
+  const baseForm = normalizeCalculationFormSchema(schema);
+  const form = deepClone(baseForm);
+  const targetField = findFieldByDataName(form.elements, fieldDataName);
+  if (targetField && targetField.type === 'CalculatedField') {
+    targetField.calculate = normalizedExpression;
+  }
   const resolver = new ContextResolver(form);
-  const executionContext = buildExecutionContext(form, fieldDataName, resolver);
+  const executionContext = buildCalculationExecutionContext(form, fieldDataName, resolver);
 
   if (normalizedExpression.trim().length === 0) {
     addIssue(
@@ -590,7 +519,7 @@ export function analyzeCalculationExpression({
     );
   }
 
-  for (const reference of extractFieldReferenceMatches(normalizedExpression)) {
+  for (const reference of extractStaticFieldReferenceMatches(normalizedExpression)) {
     if (!referencedFieldNames.has(reference.fieldName)) {
       referencedFieldNames.add(reference.fieldName);
       referencedFields.push(reference.fieldName);
@@ -633,6 +562,39 @@ export function analyzeCalculationExpression({
     }
   }
 
+  if (hasDynamicCalculationDependencies(normalizedExpression)) {
+    addIssue(
+      issues,
+      issueKeys,
+      createIssue({
+        code: 'dynamic_calculation_dependency',
+        severity: 'warning',
+        message:
+          'This expression uses dynamic field access through EVAL(). Runtime evaluation will fall back to bounded stabilization.',
+      })
+    );
+  }
+
+  if (targetField?.type === 'CalculatedField') {
+    const dependencyPlan = buildCalculationDependencyPlan(form, resolver);
+    const targetNode = dependencyPlan.nodesByDataName.get(fieldDataName);
+    const targetComponent = targetNode?.componentId
+      ? dependencyPlan.componentsById.get(targetNode.componentId)
+      : null;
+
+    if (targetComponent?.isCyclic) {
+      addIssue(
+        issues,
+        issueKeys,
+        createIssue({
+          code: 'calculated_field_cycle',
+          severity: 'error',
+          message: `CalculatedField dependency cycle detected: ${targetComponent.fieldNames.join(' -> ')}.`,
+        })
+      );
+    }
+  }
+
   return {
     valid: !issues.some((issue) => issue.severity === 'error'),
     issues,
@@ -673,23 +635,20 @@ export function createCalculationPreviewSession({
   security = DEFAULT_SECURITY_CONFIG,
 }) {
   const simulationSchema = cloneSimulationSchema(schema);
-  const form = normalizeFormSchema(simulationSchema);
+  const form = normalizeCalculationFormSchema(simulationSchema);
   const targetField = findFieldByDataName(form.elements, fieldDataName);
 
   if (!targetField) {
     return {
       run: () =>
-        createSimulationErrorResult(
-          `Field '${fieldDataName}' does not exist in the form schema.`
-        ),
+        createSimulationErrorResult(`Field '${fieldDataName}' does not exist in the form schema.`),
       dispose: () => {},
     };
   }
 
   if (targetField.type !== 'CalculatedField') {
     return {
-      run: () =>
-        createSimulationErrorResult(`Field '${fieldDataName}' is not a CalculatedField.`),
+      run: () => createSimulationErrorResult(`Field '${fieldDataName}' is not a CalculatedField.`),
       dispose: () => {},
     };
   }
@@ -739,9 +698,13 @@ export function createCalculationPreviewSession({
 
         const simulatedResult = engineState.values[fieldDataName];
         const runtimeError =
-          runtimeDiagnostics.find((diagnostic) => diagnostic.fieldName === fieldDataName)
+          runtimeDiagnostics.find(
+            (diagnostic) =>
+              diagnostic.fieldName === fieldDataName &&
+              (diagnostic.severity || 'error') !== 'warning'
+          )?.message ||
+          runtimeDiagnostics.find((diagnostic) => (diagnostic.severity || 'error') !== 'warning')
             ?.message ||
-          runtimeDiagnostics[0]?.message ||
           null;
 
         return {

package/src/utilities/value-equality.js

@@ -0,0 +1,54 @@
+function isPlainObject(value) {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  return Object.prototype.toString.call(value) === '[object Object]';
+}
+
+export function areStructuredValuesEqual(left, right) {
+  if (Object.is(left, right)) {
+    return true;
+  }
+
+  if (left instanceof Date && right instanceof Date) {
+    return left.getTime() === right.getTime();
+  }
+
+  if (Array.isArray(left) && Array.isArray(right)) {
+    if (left.length !== right.length) {
+      return false;
+    }
+
+    for (let index = 0; index < left.length; index += 1) {
+      if (!areStructuredValuesEqual(left[index], right[index])) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  if (isPlainObject(left) && isPlainObject(right)) {
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+
+    if (leftKeys.length !== rightKeys.length) {
+      return false;
+    }
+
+    for (const key of leftKeys) {
+      if (!Object.prototype.hasOwnProperty.call(right, key)) {
+        return false;
+      }
+
+      if (!areStructuredValuesEqual(left[key], right[key])) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  return false;
+}