chore: add indictment support to Bavet's Node Network

[Christopher-Chianelli]

Each tuple now have an IndictmentSource field. This field is set to IndictmentSource.DISABLED when indictments are disabled, which is used to exit early and avoid work only required for indictments. ConstraintMatchPolicy have two new values:

• ENABLED_WITHOUT_JUSTIFICATIONS_AND_INDICTMENTS this has the previous behaviour of ENABLED_WITHOUT_JUSTIFICATIONS; has constraint matches but no justifications nor indictments
• ENABLED_WITHOUT_INDICTMENTS this includes justifications but not indictments

ENABLED was changed to include both justifications and indictments instead of just justifications. ENABLED_WITHOUT_JUSTIFICATIONS was changed to include indictments.

The actual work each node does is pretty simple. Do note that the attach IndictmentSource does not change after an insert:

• forEach: if indictments are enabled, set the source of the tuple to a RootIndictmentSource (perhaps LeafIndictmentSource would be a better name) on insert. Retract and update do no extra work; retract removes the tuple (and hence the indictment source and potential constraint match), and update does not change the instance tracked.
• filter: not a node, and does not affect what object is indicted.
• map/expand/flatten: these creates new tuples from a source tuple, and simply copy the source's indictment source on insert. Update and retract do not need to do anything following the same reasoning as forEach`.
• join: on insert, set the indictment source of the joined tuple to a JoinedIndictmentSource that have a reference to both the left and right tuples' indictment sources.
• groupBy: on insert, set the indictment source of the group's tuple to an aggregation containing the indictment sources of the tuples inside the group. On update, remove the tuple's indictment source from the old group aggregation and add it to the new group aggregation. On retract, remove the tuple's indictment source from the aggregation.
• distinct: this is groupBy in a trenchcoat and behaves similarly.
• concat: behaves similarly to map/expand/flatten, since the left side and right side act independently and don't affect each other.
• ifExists/ifNotExists: The most complex of the bunch. When indictments are enabled, it takes a drastically different path than normal. In particular, right tuple will propagate updates even if the corresponding left tuple is not update. This is to prevent constraint matches with stale indictments referring to removed/retracted entities/problem facts. Additional tuple iteration occurs for indexed ifExists nodes so the tuple's indictments are up to date when the left tuple changes. Moreover, since ifExists does not create a new tuple but still adds to the indictment, the same indictment source is used, but the indictment source's support map for the key corresponding to the ifExists node's id is updated.
• precompute: Since it uses an independent node network, its node's ids do not correspond to the outer node network's node ids. As such, the indictment support map of the produced tuples must be aggregated along with the original indictment source.

Each constraint is now aware of the ids of the nodes that affect the constraint. It uses it when creating constraint matches to iterate through the support map so it does not indict objects from other constraints with ifExists that so happen to share the same tuple. Each IndictmentSource is iterated in a tree like matter to collect a set of unique indicted objects which is converted to a list inside the actual ConstraintMatch.

The vast majority of the changes were making all existing ConstraintStream tests aware of indictments. assertMatch was changed so it sets the indictment list to the justifications, which work for some but not all tests. For the other tests, withIndictedObjects is used to set the expected indicted objects for each match.

Note: I am aware of the stale "NOTE: By not propagating here, ..." comment in IfExistsNode and will remove it.
Note: I am aware that the code under if (testFiltering(...)) in IfExistsNode should do a branch depending on if indictments are enabled and call the right method (was written before the change to keep the indictments up to date and the two methods were not too different from each other).
Note: I am aware the carnality and storeSize methods added to Tuple can be removed; they are an artifact from when tuple cloning were used for ifExists's indictment enabled path.

[triceo]

First read-through. An elegant solution, was expecting this to be more code; not happy with some bits, though. Let's try to adjust if we can.

Before we move further though, I believe we need to have some clarity on how stable this is. We have the turtle tests - let's run them on this. (They may need some ad-hoc adjusting to be able to run with indictments.) If at the same time we can gather move speed data from them, we can compare to non-indictment runs and have a decent idea as to how much slower this will be.

[triceo]

Not excited that we're effectively creating more and more shared mutable state. Let's try to keep these things final and supplied at construction time. These "half-initialized" lazy objects make reasoning about the functionality/interactions significantly more difficult.

[Christopher-Chianelli]

Node ids are set in reverse order, so we do not know them until after construction of the Scorer.

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[Christopher-Chianelli]

For benchmarking purposes, I added PreviewFeature.SOLVE_WITH_INDICTMENTS, which can be used to solve with indictments enabled.

[triceo]

First read.

Other than the questions inline, I think we should think about what happens with other score directors (easy, incremental) when indictments are enabled. Easy probably fails with justifications already, but incremental does have some support for justifications AFAIK, so we should consider adding support for indictments there as well.

[triceo]

I am not aware of any such model requirement.
I'm assuming that this class came out of the conversation with Geoff?

[Christopher-Chianelli]

It is not a requirement for a model to have seperate solver and rest types, but I know a quite a few cases where they do use seperate solver and rest types. This class was primary created so the type field (which I later realized was neccessary so a frontend can identify the object that was serialized without the user manually adding it to their object) can be customized if they do not want it to be the canonical name of the class.

[triceo]

What is the value when indictments are disabled?

[Christopher-Chianelli]

Currently a empty list.

[triceo]

As long as it's the same behavior with justifications, I'm good.

[triceo]

IMO it should be documented somewhere what the behavior of indictments is supposed to be in each node. In ifExists, it is the least obvious.