Expected over references

[steve-downey]

Expected over References — Implementation of D4280R0

Summary

This PR implements four partial specializations of beman::expected that allow reference types as T and/or E, as proposed in D4280R0 (Expected over References):

Specialization	Storage	Status
expected<T&, E>	T* + union { E } + bool	Step 7
expected<T, E&>	union { T } + E* + bool	Step 8
expected<T&, E&>	T* + E* + bool	Step 9
expected<void, E&>	E* + bool	Step 10

Test count: 708 total — 654 positive Catch2 tests + 54 negative compile tests documenting every constraint violation.

CI: 93 checks green across GCC 11–16, Clang 17–23 (libstdc++ and libc++), AppleClang, and MSVC C++23.

---

Design decisions

All four specializations follow the semantics established by P2988 (std::optional<T&>):

Rebind on assignment. Assignment rebinds the internal pointer rather than assigning through. a = b makes a point at the same object as b; it does not modify the object a previously pointed at. This matches optional<T&> and avoids the assign-through bugs documented in P3168.

Shallow const. const expected<T&, E> returns a non-const T&. The constness of the wrapper does not propagate to the referent, matching T* const semantics.

No unexpected<G> construction for E& specializations. Constructing expected<T, E&> from unexpected<G> would bind E& to a member of a temporary, creating a dangling reference. These constructors are deleted. Use expected<T, E&>(unexpect, lvalue_ref) instead.

Dangling reference prevention. A detail::reference_constructs_from_temporary_v concept guards every constructor that could bind a reference to a temporary. When it fires, a deleted overload with an explanatory message is selected. The C++23 std::reference_constructs_from_temporary_v trait is used when available (__cpp_lib_reference_from_temporary), with a concept fallback for older standard libraries.

---

Reading the code

Two reviewer guides are included in docs/:

• docs/human-design-review-guide.md — covers the 10 architectural decisions that shaped this implementation, including the tradeoffs of flat vs. factored specializations, the two diagnostic modes for dangling reference rejection, and gaps in the test suite.
• docs/llm-code-review-guide.md — mechanical verification checklist against C++26 standardese constraints and mandates.

---

Known gaps (from the review guide)

• No constraint test files for expected<T, E&>, expected<T&, E&>, or expected<void, E&>. The primary and expected<T&, E> specializations have _constraints.test.cpp files with static_assert(!is_constructible_v<...>) patterns; the other three do not.
• No triviality tests for reference specializations. expected<T&, E&> and expected<void, E&> are unconditionally trivially copyable/movable/destructible (pointer-only storage) but this is not systematically asserted.
• No dedicated monadic constraint tests for reference specializations.

These gaps are known and recorded; the intent is to address them in follow-on work once the design is reviewed and stabilized.

---

Scope note

The flat, six-specialization structure mirrors how libstdc++, libc++, and the MSVC STL implement optional and expected — each specialization is self-contained and readable independently against the proposed standard wording. The ~4400-line single-header cost is the tradeoff for maximal auditability.