anchor.diff:  }
   ----
   
  +<<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 must be a one to one relationship.
  +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"]
  
positive.code: ==== 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.
  
  [source,java,options="nowrap"]
  ----
  
negative.code: }
  ----
  
  <<shadowVariableIntroduction,Register this class as a planning entity.>>
  
  [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 either.
  ====
  
  
  