Add `Residual.possible_bool_outcomes()` method

[luxas]

Category

User level API features/changes

Describe the feature you'd like to request

As discussed in #1895 (comment)

Add a function Residual::possible_bool_outcomes(&self) -> Option<HashSet<PossibleBoolOutcome>>, where the PossibleBoolOutcome enum has True, False, Error variants.

None is returned if the residual does not return a boolean, or alternatively we just name this "possible outcomes", and include NonBool as one of the variants.

This would mean that even for those Residuals whose LHS is not error-free (and thus automatically couldn't be folded to true or false), possible_bool_outcomes for residuals would the following:

• never-true resource.whatever + 1 == 2 && false => HashSet::new(False, Error),
• never-false resource.whatever + 1 == 2 || true => HashSet::new(True, Error),
• error-free expressions like resource in Group::"foo" => HashSet::new(True, False), and
• arbitrary expressions like resource.whatever + 1 == 2 => HashSet::new(True, False, Error).

If Residual::possible_bool_outcomes returns only a single item, it is known to be a concrete value (true, false, error). The HashSet can never be empty.

This functionality then allows advanced users to filter never-true policies, if the specific use-case of the caller anyways would ignore any error that would arise from concrete evaluation.

I'm planning to submit a PR for this as discussed with @john-h-kastner-aws in #2091

Describe alternatives you've considered

Keep this just downstream, however, this seems to be a commonly-occurring request, based on the number of people that have asked why TPE doesn't fold <possibly-erroring-residual> && false to false

Additional context

No response

Is this something that you'd be interested in working on?

• 👋 I may be able to implement this feature request
• ⚠️ This feature might incur a breaking change