feat: support sourcing declarative shadow variables from planning list variable elements

[fodzal]

What

Follow-up to #2469. An entity declaring a @PlanningListVariable can now use a
@ShadowSources path such as "visits[].endTime" to depend on a declarative shadow
variable of the list variable's elements:

@PlanningListVariable
List<Visit> visits;

@ShadowVariable(supplierName = "endTimeSupplier")
LocalDateTime endTime;

@ShadowSources("visits[].endTime")
LocalDateTime endTimeSupplier() {
    return visits.isEmpty() ? departureTime : visits.getLast().getEndTime();
}

This is the capability discussed in the #2469 review: accessing the declarative shadow
variables of entities inside the @PlanningListVariable, with the edges of the graph
created and updated as the list variable changes. The fail-fast added by #2469 now points
users to this syntax.

How

• RootVariableSource accepts a [] segment on a genuine list variable declared on the
  root entity, producing the new ParentVariableType.LIST_ELEMENT. The path must end on a
  declarative shadow variable of the element (optionally reached via a fact).
• Fan-in edges (element.shadowVariable -> entity.shadowVariable) are created from the
  list variable's contents when the graph is built. They are registered as initial dynamic
  edges, not fixed edges, so a dependency loop through them is treated as breakable by the
  solver instead of failing fast.
• before/afterListVariableChanged events are forwarded to the declarative shadow
  variable session, which incrementally removes/adds the fan-in edges for the changed
  range and always marks the target variable as changed (covering removals and
  reorderings). Models without list element sources skip this entirely.
• Thanks to the edges, the topological order guarantees the target variable is computed
  once per move, after all its elements' shadow variables have settled.
• GraphStructure classifies models with list element sources as arbitrary, since the
  graph's edges change during solving; the grouped-updater decision is static for the same
  reason.

Testing

• Path parsing: valid values[].shadowVar forms and the new fail-fasts
  (non-declarative element variable, list variable reached via another member) in
  RootVariableSourceTest.
• ListElementShadowVariableTest: SolutionManager.updateShadowVariables (including
  empty lists and mutations between calls) and two FULL_ASSERT solver runs, one from an
  uninitialized solution and one from an initialized solution (exercising the initial
  edge seeding).
• A dedicated testdomain/shadow/list_element domain is used instead of extending
  simple_list, because adding a list element source there would reclassify it away from
  SINGLE_DIRECTIONAL_PARENT and lose that structure's coverage.
• Full core test suite passes.

[Christopher-Chianelli]

I will do my own testing of this to verify correctness. Some comments.

[fodzal]

Thanks @Christopher-Chianelli, I have done the required changes.

I have tested that on a simplified model (VRP with sequential vehicles), it works well.

[triceo]

@fodzal As a side-effect of some other changes we made, there is now a conflict in this PR. Can you please resolve it?

We'll take a look at this afterwards and provide a final review.

[fodzal]

@triceo Merged main (incl. #2525) with 1 minor conflit resolved. I re-verified against the new ShadowVariableSupport — it works well.

[Christopher-Chianelli]

Code overall looks good, will do more testing before approval. I have written code similar to this about 1 year ago in my attempt to implement this feature, but it had score corruptions back then. But the feature I was implementing was more varied (i.e. also included Collection based @InverseShadowVariable), and it is possible we fixed a bug that was causing the original implementation to fail.

[Christopher-Chianelli]

LGTM when green.

[triceo]

@fodzal The final review is in. Once you resolve the comments, and once CI is green, we will merge the PR.

(The native build is currently failing, but that is likely unrelated to this PR and I won't hold you to fixing that one.)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
85.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud