effects: add new @consistent_overlay macro

[aviatesk]

This PR serves to replace #51080 and close #52940.
It extends the :nonoverlayed to UInt8 and introduces the CONSISTENT_OVERLAY effect bit, allowing for concrete evaluation of overlay methods using the original non-overlayed counterparts when applied. Additionally, this PR adds a new effect override called :consistent_overlay.
I've also included a relatively accurate description of :consistent_overlay, as pointed out in #51080. Quoting from the newly added docstrings:

:consistent_overlay

The :consistent_overlay setting asserts that any overlayed methods potentially called by
the method are :consistent with their original, non-overlayed counterparts. For the exact
definition of :consistent, refer to the earlier explanation.

More formally, when evaluating a generic function call f(x) at a specific world-age i,
and the regular method call fᵢ(x) is redirected to an overlay method fᵢ′(x), this
setting requires that fᵢ(x) ≡ fᵢ′(x).

!!! note
Note that the requirements for :consistent-cy include not only that the return values
are egal, but also that the manner of termination is the same.
However, it's important to aware that when they throw exceptions, the exceptions
themselves don't necessarily have to be egal as explained in the note of :consistent.
In other words, if fᵢ(x) throws an exception, this settings requires fᵢ′(x) to
also raise one, but the exact exceptions may differ.

!!! note
This setting isn't supported at the callsite; it has to be applied at the definition
site. Also, given its nature, it's expected to be used together with Base.Experimental.@overlay.

Still, the explanation might not be comprehensive enough. I welcome any feedback.

---

EDIT: Now this feature is implemented with a new macro @consistent_overlay instead of extending the override set of @assume_effects.

[oscardssmith]

could we also add a weaker version of this effect that only requires the overlay to return an egal answer when the regular function returns an answer? (e.g. for things like NaNMath)

[aviatesk]

That sounds exactly like the requirements for :consistent_overlay. Can you explain how that version is considered weaker?

[oscardssmith]

If I'm reading this right, it wouldn't be valid to use this extension for log_overlay(x) = x < 0 ? NaN : log(x) since log_overlay returns a value rather than throwing for negative numbers.

[aviatesk]

Ah, did you mean @overlay NAN_MATH_TABLE log(x) = x < 0 ? NaN : log(x), right?
We can create such a :nonoverlay effect bit (, which allows concrete evaluation with bailing out of it if the original method's execution raises an issue). But that nuanced setting would be more complicated than the already complex :consistent_overlay, so I'd prefer to introduce it only when there's a demonstrated need.

[Keno]

I'm ok with this, but it seems a bit weird to put this on @assume_effects. I don't even mind this going into in the (internal) EffectsOverride, I'm just thinking in terms of where to put the user-facing part of this. I think it makes more sense as an option to the @overlay macro.

[aviatesk]

I think it makes more sense as an option to the @overlay macro.

I agree. I've created a new @consistent_overlay macro and included a thorough documentation.