anchor.diff:  ==== Custom `VariableListener`
   
   To update a shadow variable, Planner uses a ``VariableListener``.
  -To define a custom shadow variable, write a custom ``VariableListener``: implement the interface and annotate it on the shadow variable that needs to change.
  +To define a custom shadow variable, write a custom ``VariableListener``:
  +implement the interface and annotate it on the shadow variable that needs to change.
   
   [source,java,options="nowrap"]
   ----
  
positive.code: }
  ----
  
  [WARNING]
  ====
  The input planning problem of a `Solver` must not violate bi-directional relationships.
  If A points to B, then B must point to A.
  Planner will not violate that principle during planning, but the input must not violate it.
  ====
  
  
  
negative.code: }
  ----
  
  <<shadowVariableIntroduction,Register this class as a planning entity.>>
  The `sourceVariableName` property is the name of the genuine planning variable on the return type of the getter (so the name of the genuine planning variable on the _other_ side).
  
  [NOTE]
  ====
  The shadow property, which is a ``Collection``, can never be ``null``.
  If no genuine variable is referencing that shadow entity, then it is an empty ``Collection``.
  Furthermore it must be a mutable `Collection` because once the Solver starts initializing or changing genuine planning variables,
  it will add and remove to the ``Collection``s of those shadow variables accordingly.
  ====
  
  For a chained planning variable, the bi-directional relationship is always a one to one relationship.
  In that case, the genuine side looks like this:
  
  [source,java,options="nowrap"]
  