Module agentforge4j.config.loader
Package com.agentforge4j.config.loader.validation

Class WorkflowValidator

java.lang.Object
com.agentforge4j.config.loader.validation.WorkflowValidator
public final class WorkflowValidator extends Object
Structural and cross-reference validation checks run against loaded workflow and agent definitions.

  • Constructor Details

    • WorkflowValidator

      public WorkflowValidator(int maxTraversalDepth)
      Creates a validator whose traversal-based checks fail fast past maxTraversalDepth levels of branch, retry-fallback, blueprint, or inline nested-workflow nesting.
      Parameters:
      maxTraversalDepth - the maximum nesting depth to traverse before failing fast; must be greater than zero. Callers with no reason to diverge from the traversal engine's own default should pass WorkflowTreeWalker.MAX_TRAVERSAL_DEPTH.

  • Method Details

    • validateWorkflowRefs

      public void validateWorkflowRefs(Map<String,WorkflowDefinition> workflows)
      Verifies that workflow references point to known workflows.
      Parameters:
      workflows - workflows to validate
      Throws:
      IllegalArgumentException - when a workflow reference targets an unknown workflow

    • validateBlueprintRefs

      public void validateBlueprintRefs(Map<String,WorkflowDefinition> workflows)
      Verifies that blueprint references point to declared blueprints in the same workflow and that no blueprint nesting chain is circular.
      Parameters:
      workflows - workflows to validate
      Throws:
      BlueprintStructureException - when a blueprint reference targets an unknown blueprint, or nesting exceeds the configured traversal depth

    • validateArtifactRefs

      public void validateArtifactRefs(Map<String,WorkflowDefinition> workflows)
      Verifies that artifact references point to declared artifacts in the same workflow.
      Parameters:
      workflows - workflows to validate
      Throws:
      IllegalArgumentException - when an artifact reference targets an unknown artifact

    • validateCircularRefs

      public void validateCircularRefs(Map<String,WorkflowDefinition> workflows)
      Verifies that workflow reference graphs do not contain cycles.
      Parameters:
      workflows - workflows to validate
      Throws:
      IllegalStateException - when a circular workflow reference is detected

    • validateRetryStepRefs

      public void validateRetryStepRefs(Map<String,WorkflowDefinition> workflows)
      Verifies that RetryPreviousBehaviour references target a known step reachable within the retry step's own enclosing scope (the root workflow, or the nearest inline nested WorkflowDefinition — blueprint bodies share their enclosing workflow's scope).
      Parameters:
      workflows - workflows to validate
      Throws:
      IllegalArgumentException - when a retry step reference targets an unknown step id

    • validateReachableStepIdUniqueness

      public void validateReachableStepIdUniqueness(Map<String,WorkflowDefinition> workflows)
      Verifies that, for every workflow treated as a run root, no step id is reachable from more than one structural location across the reachable graph — the root, the blueprints it references, and the sub-workflows its WORKFLOW steps reach. This is the exact graph the runtime resolves a step against at a gate or input submission; rejecting the ambiguity here turns an otherwise mid-run IllegalStateException into a load-time error.

      Validation is per-root: the same id appearing in two different root workflows is fine (they are separate runs), while a single sub-workflow or blueprint reached by more than one path within one root collapses to a single location and is not ambiguous.

      Parameters:
      workflows - workflows to validate
      Throws:
      IllegalStateException - when a reachable step id resolves to two or more structural locations

    • validateValidateBehaviourContracts

      public void validateValidateBehaviourContracts(Map<String,WorkflowDefinition> workflows)
      Verifies that every VALIDATE step's context-equality contracts reference an artifact in that step's own requiredArtifacts allowlist. A contract pointing at a path outside the allowlist can never be satisfied at runtime (that artifact is never captured for the step), so it is a config error caught here at load time.
      Parameters:
      workflows - workflows to validate
      Throws:
      IllegalArgumentException - when a contract references an artifact outside the step's allowlist

    • validateRequirements

      public void validateRequirements(Map<String,WorkflowDefinition> workflows)
      Verifies the structural integrity of each workflow's requirements declarations: requirement-id uniqueness, that a targeted stepId resolves to a real step, and that no two requirements of the same type target the same site. Requirement type, action values, and default payloads are opaque and are not interpreted here.
      Parameters:
      workflows - workflows to validate
      Throws:
      IllegalArgumentException - when a requirement declaration is structurally invalid

    • validateNoCollectionSteps

      public void validateNoCollectionSteps(Map<String,WorkflowDefinition> workflows)
      Verifies that no step in any workflow uses CollectionBehaviour. The COLLECTION step type is a half-landed public surface: its sealed permit, state, and event types are kept intact for a planned future completion, but no runtime BehaviourHandler is registered for it, so a run reaching such a step can only fail deep inside execution. The JSON schema's step-type enum already omits COLLECTION, so this check only ever fires against a programmatically-constructed WorkflowDefinition tree; it exists as defense-in-depth alongside that schema gate so a future schema change cannot silently reopen the load path.
      Parameters:
      workflows - workflows to validate
      Throws:
      IllegalArgumentException - when a step uses CollectionBehaviour

    • validateAgentRefs

      public void validateAgentRefs(Map<String,WorkflowDefinition> workflows, Map<String,AgentDefinition> agents)
      Verifies that every agent reference in every workflow resolves to a known agent id.
      Parameters:
      workflows - workflows whose agent references are checked
      agents - available agents keyed by id
      Throws:
      UnresolvedAgentReferenceException - when one or more agent references are unresolved