From 004a630c69c8958af79d7181f764c6f37f259352 Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Thu, 10 Sep 2026 15:50:50 +0800
Subject: [PATCH 01/14] restore the vendored iceberg::expected backport,
 updated to zeus-cpp/expected v1.4.0

Co-authored-by: Junwang Zhao <zhjwpku@gmail.com>
---
 .github/.licenserc.yaml           |    1 +
 LICENSE                           |   28 +
 src/iceberg/expected.h            | 2626 +++++++++++++++++++++++++++++
 src/iceberg/test/CMakeLists.txt   |    1 +
 src/iceberg/test/expected_test.cc |  636 +++++++
 5 files changed, 3292 insertions(+)
 create mode 100644 src/iceberg/expected.h
 create mode 100644 src/iceberg/test/expected_test.cc

diff --git a/.github/.licenserc.yaml b/.github/.licenserc.yaml
index a667c903e..dcfcd64f6 100644
--- a/.github/.licenserc.yaml
+++ b/.github/.licenserc.yaml
@@ -29,6 +29,7 @@ header:
     - 'LICENSE'
     - 'NOTICE'
     - 'requirements.txt'
+    - 'src/iceberg/expected.h'
     - 'src/iceberg/util/murmurhash3_internal.*'
     - 'src/iceberg/test/resources/**'
     - 'src/iceberg/catalog/hive/gen-cpp/**'
diff --git a/LICENSE b/LICENSE
index d0429e24b..6d0d88e91 100644
--- a/LICENSE
+++ b/LICENSE
@@ -230,6 +230,34 @@ License: https://www.apache.org/licenses/LICENSE-2.0
 
 --------------------------------------------------------------------------------
 
+This product includes code from zeus-cpp/expected.
+
+* src/iceberg/expected.h is adapted from zeus-cpp/expected.
+
+Copyright: 2024 zeus-cpp.
+Home page: https://github.com/zeus-cpp/expected
+License: MIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
 This product bundles utf8proc, which is available under the MIT License:
 
 utf8proc is a software package originally developed by Jan Behrens and the rest
diff --git a/src/iceberg/expected.h b/src/iceberg/expected.h
new file mode 100644
index 000000000..69c60f3a5
--- /dev/null
+++ b/src/iceberg/expected.h
@@ -0,0 +1,2626 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2024 zeus-cpp
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/// \file iceberg/expected.h
+/// \brief A C++20 backport of C++23 `std::expected`, used as the storage type
+/// behind `iceberg::Result`.
+///
+/// Purpose: the library itself may be built as C++23, but its public headers
+/// must stay consumable from C++20 translation units. `std::expected` is a
+/// C++23 library feature, so `iceberg::Result<T>` (see iceberg/result.h) is
+/// defined in terms of `iceberg::expected` instead. The API mirrors
+/// `std::expected` (including the monadic `and_then`, `or_else`, `transform`
+/// and `transform_error`), so code can be written as if against the standard
+/// type.
+///
+/// Upstream: https://github.com/zeus-cpp/expected (MIT),
+/// include/zeus/expected.hpp at tag v1.4.0
+/// (f9dde3b062f1b3a5d1a9f2888e4b6f6d2303557b).
+///
+/// Local changes (search for "iceberg:" for the non-mechanical ones):
+/// * Namespace `zeus` and its versioned inline ABI namespace replaced by plain
+///   `iceberg`, so symbol names stay stable across upstream updates; macros
+///   renamed from `ZEUS_EXPECTED_*` to `ICEBERG_EXPECTED_*`, and the upstream
+///   version macros removed.
+/// * Public classes annotated with `ICEBERG_EXPORT`, except the primary
+///   `expected` template, which uses `ICEBERG_TEMPLATE_CLASS_EXPORT` (empty on
+///   MSVC, where exporting a class template breaks the Windows build).
+/// * `[[nodiscard]]` added to `unexpected` and `expected`.
+/// * The default constructor no longer requires `T` to be default
+///   constructible, so `expected<T, E>` can hold types with no (or a private)
+///   default constructor, which MSVC otherwise tried to instantiate.
+/// * When `std::expected` is available, `iceberg::expected` can also be
+///   constructed from `std::unexpected<G>`, so library code compiled as C++23
+///   that still spells errors with `std::unexpected` keeps working.
+/// * Reformatted with clang-format.
+///
+/// History:
+/// - apache/iceberg-cpp#40 first vendored zeus-cpp/expected (v1.2.0) while the
+///   project targeted C++20.
+/// - apache/iceberg-cpp#139 raised the project to C++23 and removed the header
+///   in favor of `std::expected`, which made C++23 a requirement for users of
+///   the public headers too.
+/// - apache/iceberg-cpp#936 vendored it again, updated to v1.4.0, so the public
+///   headers work in C++20 again.
+///
+/// Once C++23 can be required of all consumers, this header can be dropped and
+/// `iceberg::Result` aliased back to `std::expected`.
+
+#pragma once
+
+#include <exception>
+#include <functional>
+#include <type_traits>
+#include <utility>
+#include <version>
+#if defined(__cpp_lib_expected) && __cpp_lib_expected >= 202202L
+#  include <expected>
+#endif
+
+#include "iceberg/iceberg_export.h"
+
+// NOLINTBEGIN
+
+#if defined(_MSVC_LANG)
+#  define ICEBERG_EXPECTED_CPLUSPLUS _MSVC_LANG
+#else
+#  define ICEBERG_EXPECTED_CPLUSPLUS __cplusplus
+#endif
+
+#if ICEBERG_EXPECTED_CPLUSPLUS < 201'703L
+static_assert(false, "This expected variant requires C++17");
+#endif
+
+#if ICEBERG_EXPECTED_CPLUSPLUS >= 202'002L
+#  define ICEBERG_EXPECTED_CONSTEXPR_DTOR constexpr
+#else
+#  define ICEBERG_EXPECTED_CONSTEXPR_DTOR
+#endif
+
+// Detect exception support
+#if defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)
+#  define ICEBERG_EXPECTED_THROW(e) (throw(e))
+#else
+#  define ICEBERG_EXPECTED_THROW(e) ((void)(e), std::terminate())
+#endif
+
+namespace iceberg {
+
+namespace expected_detail {
+
+template <class T, class... Args>
+constexpr T* construct_at(T* p, Args&&... args) noexcept(
+    noexcept(::new (static_cast<void*>(p)) T(std::forward<Args>(args)...))) {
+#if ICEBERG_EXPECTED_CPLUSPLUS >= 202'002L
+  return std::construct_at(p, std::forward<Args>(args)...);
+#else
+  return ::new (static_cast<void*>(p)) T(std::forward<Args>(args)...);
+#endif
+}
+
+template <class T>
+struct remove_cvref {
+  using type = std::remove_cv_t<std::remove_reference_t<T>>;
+};
+template <class T>
+using remove_cvref_t = typename remove_cvref<T>::type;
+
+template <class T, template <class...> class Template>
+inline constexpr bool is_specialization_v =
+    false;  // true if and only if T is a specialization of Template
+template <template <class...> class Template, class... Types>
+inline constexpr bool is_specialization_v<Template<Types...>, Template> = true;
+
+template <class T, class U>
+using is_void_or = std::conditional_t<std::is_void_v<T>, std::true_type, U>;
+template <class T, class U>
+inline constexpr bool is_void_or_v = is_void_or<T, U>::value;
+
+template <class T>
+inline constexpr bool is_trivially_destructible_or_void_v =
+    is_void_or_v<T, std::is_trivially_destructible<T>>;
+
+template <class T>
+inline constexpr bool is_trivially_copy_constructible_or_void_v =
+    is_void_or_v<T, std::is_trivially_copy_constructible<T>>;
+
+template <class T>
+inline constexpr bool is_trivially_move_constructible_or_void_v =
+    is_void_or_v<T, std::is_trivially_move_constructible<T>>;
+
+template <class T>
+inline constexpr bool is_trivially_copy_assignable_or_void_v =
+    is_void_or_v<T, std::is_trivially_copy_assignable<T>>;
+
+template <class T>
+inline constexpr bool is_trivially_move_assignable_or_void_v =
+    is_void_or_v<T, std::is_trivially_move_assignable<T>>;
+
+template <class T>
+inline constexpr bool is_nothrow_copy_constructible_or_void_v =
+    is_void_or_v<T, std::is_nothrow_copy_constructible<T>>;
+
+template <class T>
+inline constexpr bool is_nothrow_move_constructible_or_void_v =
+    is_void_or_v<T, std::is_nothrow_move_constructible<T>>;
+
+template <class T>
+inline constexpr bool is_default_constructible_or_void_v =
+    is_void_or_v<T, std::is_default_constructible<T>>;
+
+template <class T>
+inline constexpr bool is_copy_constructible_or_void_v =
+    is_void_or_v<T, std::is_copy_constructible<T>>;
+
+template <class T>
+inline constexpr bool is_move_constructible_or_void_v =
+    is_void_or_v<T, std::is_move_constructible<T>>;
+
+template <class T>
+inline constexpr bool is_copy_assignable_or_void_v =
+    is_void_or_v<T, std::is_copy_assignable<T>>;
+
+template <class T>
+inline constexpr bool is_move_assignable_or_void_v =
+    is_void_or_v<T, std::is_move_assignable<T>>;
+
+template <class From, class To>
+inline constexpr bool is_nothrow_convertible_v =
+    noexcept(static_cast<To>(std::declval<From>()));
+
+template <class Lhs, class Rhs, class = void>
+struct is_equality_result_convertible_to_bool : std::false_type {};
+
+template <class Lhs, class Rhs>
+struct is_equality_result_convertible_to_bool<
+    Lhs, Rhs,
+    std::void_t<decltype(std::declval<const Lhs&>() == std::declval<const Rhs&>())>>
+    : std::is_convertible<
+          decltype(std::declval<const Lhs&>() == std::declval<const Rhs&>()), bool> {};
+
+template <class Lhs, class Rhs>
+inline constexpr bool is_equality_result_convertible_to_bool_v =
+    is_equality_result_convertible_to_bool<Lhs, Rhs>::value;
+
+constexpr bool implicitly_convert_to_bool(bool value) noexcept { return value; }
+
+template <class Lhs, class Rhs, class = void>
+struct is_nothrow_equality_result_convertible_to_bool : std::false_type {};
+
+template <class Lhs, class Rhs>
+struct is_nothrow_equality_result_convertible_to_bool<
+    Lhs, Rhs,
+    std::void_t<decltype(implicitly_convert_to_bool(std::declval<const Lhs&>() ==
+                                                    std::declval<const Rhs&>()))>>
+    : std::bool_constant<noexcept(implicitly_convert_to_bool(
+          std::declval<const Lhs&>() == std::declval<const Rhs&>()))> {};
+
+template <class Lhs, class Rhs>
+inline constexpr bool is_nothrow_equality_result_convertible_to_bool_v =
+    is_nothrow_equality_result_convertible_to_bool<Lhs, Rhs>::value;
+
+}  // namespace expected_detail
+
+template <class E>
+class unexpected;
+
+namespace expected_detail {
+
+template <class E>
+struct is_error_type_valid : std::true_type {
+  static_assert(std::is_object_v<E>, "E must be an object type");
+  static_assert(!std::is_array_v<E>, "E must not be an array");
+  static_assert(!std::is_const_v<E>, "E must not be const");
+  static_assert(!std::is_volatile_v<E>, "E must not be volatile");
+  static_assert(!expected_detail::is_specialization_v<std::remove_cv_t<E>, unexpected>,
+                "E must not be unexpected");
+};
+template <class T>
+inline constexpr bool is_error_type_valid_v = is_error_type_valid<T>::value;
+
+}  // namespace expected_detail
+
+template <class E>
+class ICEBERG_EXPORT [[nodiscard]] unexpected {
+ public:
+  static_assert(expected_detail::is_error_type_valid_v<E>);
+
+  unexpected() = delete;
+
+  ~unexpected() = default;
+
+  unexpected(const unexpected&) = default;
+
+  unexpected(unexpected&&) = default;
+
+  template <class... Args,
+            typename std::enable_if_t<std::is_constructible_v<E, Args...>>* = nullptr>
+  constexpr explicit unexpected(std::in_place_t, Args&&... args) noexcept(
+      std::is_nothrow_constructible_v<E, Args...>)
+      : m_val(std::forward<Args>(args)...) {}
+
+  template <class U, class... Args,
+            typename std::enable_if_t<std::is_constructible_v<
+                E, std::initializer_list<U>&, Args...>>* = nullptr>
+  constexpr explicit unexpected(
+      std::in_place_t, std::initializer_list<U> l,
+      Args&&... args) noexcept(std::is_nothrow_constructible_v<E,
+                                                               std::initializer_list<U>&,
+                                                               Args...>)
+      : m_val(l, std::forward<Args>(args)...) {}
+
+  template <class Err = E,
+            typename std::enable_if_t<std::is_constructible_v<E, Err>>* = nullptr>
+  constexpr explicit unexpected(Err&& e) noexcept(std::is_nothrow_constructible_v<E, Err>)
+      : m_val(std::forward<Err>(e)) {}
+
+  unexpected& operator=(const unexpected&) = default;
+  unexpected& operator=(unexpected&&) = default;
+
+  constexpr const E& error() const& noexcept { return m_val; }
+  constexpr E& error() & noexcept { return m_val; }
+  constexpr E&& error() && noexcept { return std::move(m_val); }
+  constexpr const E&& error() const&& noexcept { return std::move(m_val); }
+
+  constexpr void swap(unexpected& other) noexcept(std::is_nothrow_swappable_v<E>) {
+    static_assert(std::is_swappable_v<E>, "E must be swappable");
+    using std::swap;
+    swap(m_val, other.m_val);
+  }
+
+  friend constexpr void swap(unexpected& x, unexpected& y) noexcept(noexcept(x.swap(y))) {
+    x.swap(y);
+  }
+
+  template <class E2>
+  friend constexpr bool operator==(
+      const unexpected& lhs,
+      const unexpected<E2>& rhs) noexcept(noexcept(lhs.error() == rhs.error())) {
+    return lhs.error() == rhs.error();
+  }
+  template <class E2>
+  friend constexpr bool operator!=(
+      const unexpected& lhs,
+      const unexpected<E2>& rhs) noexcept(noexcept(lhs.error() != rhs.error())) {
+    return lhs.error() != rhs.error();
+  }
+
+ private:
+  E m_val;
+};
+
+// deduction guide
+template <class E>
+unexpected(E) -> unexpected<E>;
+
+struct ICEBERG_EXPORT unexpect_t {
+  explicit unexpect_t() = default;
+};
+inline constexpr unexpect_t unexpect{};
+
+template <class E>
+class bad_expected_access;
+
+template <>
+class ICEBERG_EXPORT bad_expected_access<void> : public std::exception {
+ public:
+  [[nodiscard]] const char* what() const noexcept override {
+    return "Bad expected access";
+  }
+
+ protected:
+  // LWG-4031
+  bad_expected_access() noexcept = default;
+  bad_expected_access(const bad_expected_access&) noexcept = default;
+  bad_expected_access(bad_expected_access&&) noexcept = default;
+  bad_expected_access& operator=(const bad_expected_access&) noexcept = default;
+  bad_expected_access& operator=(bad_expected_access&&) noexcept = default;
+  ~bad_expected_access() override = default;
+};
+
+template <class E>
+class ICEBERG_EXPORT bad_expected_access : public bad_expected_access<void> {
+ public:
+  explicit bad_expected_access(E e) noexcept(std::is_nothrow_move_constructible_v<E>)
+      : m_val(std::move(e)) {}
+
+  const E& error() const& noexcept { return m_val; }
+  E& error() & noexcept { return m_val; }
+  const E&& error() const&& noexcept { return std::move(m_val); }
+  E&& error() && noexcept { return std::move(m_val); }
+
+ private:
+  E m_val;
+};
+
+template <class T, class E>
+class expected;
+
+namespace expected_detail {
+
+template <class T>
+struct is_value_type_valid : std::true_type {
+  static_assert(!std::is_reference_v<T>, "T must not be a reference");
+  static_assert(!std::is_function_v<T>, "T must not be a function");
+  static_assert(!std::is_array_v<T>,
+                "T must not be an array to meet the requirements of Cpp17Destructible "
+                "when T is not cv-void");
+  static_assert(!std::is_same_v<T, std::remove_cv_t<std::in_place_t>>,
+                "T must not be in_place_t");
+  static_assert(!std::is_same_v<T, std::remove_cv_t<unexpect_t>>,
+                "T must not be unexpect_t");
+  static_assert(!expected_detail::is_specialization_v<std::remove_cv_t<T>, unexpected>,
+                "T must not be unexpected");
+};
+template <class T>
+inline constexpr bool is_value_type_valid_v = is_value_type_valid<T>::value;
+
+template <class T, class E, class U>
+using enable_forward_t = std::enable_if_t<
+    std::is_constructible_v<T, U> &&
+    !std::is_same_v<expected_detail::remove_cvref_t<U>, std::in_place_t> &&
+    !std::is_same_v<expected<T, E>, expected_detail::remove_cvref_t<U>> &&
+    !expected_detail::is_specialization_v<expected_detail::remove_cvref_t<U>,
+                                          unexpected> &&
+    (!std::is_same_v<std::remove_cv_t<T>, bool> ||  // LWG-3836
+     !expected_detail::is_specialization_v<expected_detail::remove_cvref_t<U>,
+                                           expected>) &&
+    !std::is_same_v<expected_detail::remove_cvref_t<U>, unexpect_t>  // LWG-4222
+    >;
+
+template <class T, class E, class U, class G, class UF, class GF>
+using enable_from_other_expected_t = std::enable_if_t<
+    std::is_constructible_v<T, UF> && std::is_constructible_v<E, GF> &&
+    std::disjunction_v<std::is_same<std::remove_cv_t<T>, bool>,  // LWG-3836
+                       std::negation<std::disjunction<
+                           std::is_constructible<T, expected<U, G>&>,
+                           std::is_constructible<T, expected<U, G>>,
+                           std::is_constructible<T, const expected<U, G>&>,
+                           std::is_constructible<T, const expected<U, G>>,
+                           std::is_convertible<expected<U, G>&, T>,
+                           std::is_convertible<expected<U, G>&&, T>,
+                           std::is_convertible<const expected<U, G>&, T>,
+                           std::is_convertible<const expected<U, G>&&, T>,
+                           std::is_constructible<unexpected<E>, expected<U, G>&>,
+                           std::is_constructible<unexpected<E>, expected<U, G>>,
+                           std::is_constructible<unexpected<E>, const expected<U, G>&>,
+                           std::is_constructible<unexpected<E>, const expected<U, G>>>>>>;
+
+template <class E, class U, class G, class GF>
+using enable_from_other_void_expected_t =
+    std::enable_if_t<std::is_void_v<U> && std::is_constructible_v<E, GF> &&
+                     std::negation_v<std::disjunction<
+                         std::is_constructible<unexpected<E>, expected<U, G>&>,
+                         std::is_constructible<unexpected<E>, expected<U, G>>,
+                         std::is_constructible<unexpected<E>, const expected<U, G>&>,
+                         std::is_constructible<unexpected<E>, const expected<U, G>>>>>;
+
+}  // namespace expected_detail
+
+namespace expected_detail {
+
+// Constructing the active alternative inside storage_base ensures its
+// destructor only ever observes a fully initialized value or error.
+struct construct_from_expected_t {
+  explicit construct_from_expected_t() = default;
+};
+inline constexpr construct_from_expected_t construct_from_expected{};
+
+template <class Rhs>
+constexpr bool expected_source_has_value(const Rhs& rhs) noexcept {
+  if constexpr (expected_detail::is_specialization_v<expected_detail::remove_cvref_t<Rhs>,
+                                                     expected>) {
+    return rhs.has_value();
+  } else {
+    return rhs.m_has_val;
+  }
+}
+
+template <class Rhs>
+constexpr decltype(auto) expected_source_value(Rhs&& rhs) noexcept {
+  if constexpr (expected_detail::is_specialization_v<expected_detail::remove_cvref_t<Rhs>,
+                                                     expected>) {
+    return *std::forward<Rhs>(rhs);
+  } else {
+    if constexpr (std::is_lvalue_reference_v<Rhs>) {
+      return (rhs.m_val);
+    } else {
+      return std::move(rhs.m_val);
+    }
+  }
+}
+
+template <class Rhs>
+constexpr decltype(auto) expected_source_error(Rhs&& rhs) noexcept {
+  if constexpr (expected_detail::is_specialization_v<expected_detail::remove_cvref_t<Rhs>,
+                                                     expected>) {
+    return std::forward<Rhs>(rhs).error();
+  } else {
+    if constexpr (std::is_lvalue_reference_v<Rhs>) {
+      return (rhs.m_unexpect);
+    } else {
+      return std::move(rhs.m_unexpect);
+    }
+  }
+}
+
+struct construct_with_invoke_result_t {
+  explicit construct_with_invoke_result_t() = default;
+};
+inline constexpr construct_with_invoke_result_t construct_with_invoke_result{};
+
+template <class T>
+struct [[nodiscard]] ReinitGuard {
+  static_assert(std::is_nothrow_move_constructible_v<T>);
+
+  ReinitGuard(ReinitGuard const&) = delete;
+  ReinitGuard& operator=(ReinitGuard const&) = delete;
+
+  constexpr ReinitGuard(T* target, T* tmp) noexcept : _target(target), _tmp(tmp) {}
+  ICEBERG_EXPECTED_CONSTEXPR_DTOR ~ReinitGuard() noexcept {
+    if (_target) {
+      expected_detail::construct_at(_target, std::move(*_tmp));
+    }
+  }
+  T* _target;
+  T* _tmp;
+};
+
+template <class First, class Second, class... Args>
+constexpr void reinit_expected(First& new_val, Second& old_val, Args&&... args) noexcept(
+    std::is_nothrow_constructible_v<First, Args...>) {
+  if constexpr (std::is_nothrow_constructible_v<First, Args...>) {
+    if constexpr (!std::is_trivially_destructible_v<Second>) {
+      old_val.~Second();
+    }
+    expected_detail::construct_at(std::addressof(new_val), std::forward<Args>(args)...);
+  } else if constexpr (std::is_nothrow_move_constructible_v<First>) {
+    First tmp(std::forward<Args>(args)...);
+    if constexpr (!std::is_trivially_destructible_v<Second>) {
+      old_val.~Second();
+    }
+    expected_detail::construct_at(std::addressof(new_val), std::move(tmp));
+  } else {
+    Second tmp(std::move(old_val));
+    if constexpr (!std::is_trivially_destructible_v<Second>) {
+      old_val.~Second();
+    }
+
+    expected_detail::ReinitGuard<Second> guard{std::addressof(old_val),
+                                               std::addressof(tmp)};
+    expected_detail::construct_at(std::addressof(new_val), std::forward<Args>(args)...);
+    guard._target = nullptr;
+  }
+}
+
+// Implements the storage of the values, and ensures that the destructor is
+// trivial if it can be.
+//
+// This specialization is for when `T` and `E` are trivially destructible
+template <class T, class E,
+          bool = is_trivially_destructible_or_void_v<T> &&
+                 std::is_trivially_destructible_v<E>>
+struct storage_base {
+  storage_base(storage_base const&) = default;
+  storage_base(storage_base&&) = default;
+  storage_base& operator=(storage_base const&) = default;
+  storage_base& operator=(storage_base&&) = default;
+
+  // iceberg: constrained so MSVC never instantiates T{} for a T without an
+  // accessible default constructor.
+  template <class U = T, std::enable_if_t<std::is_default_constructible_v<U>, int> = 0>
+  constexpr storage_base() noexcept(std::is_nothrow_default_constructible_v<U>)
+      : m_val(), m_has_val(true) {}
+
+  template <class Rhs>
+  constexpr storage_base(construct_from_expected_t, Rhs&& rhs) noexcept(
+      std::is_nothrow_constructible_v<
+          T, decltype(expected_detail::expected_source_value(std::declval<Rhs>()))> &&
+      std::is_nothrow_constructible_v<
+          E, decltype(expected_detail::expected_source_error(std::declval<Rhs>()))>)
+      : m_dummy(), m_has_val(expected_detail::expected_source_has_value(rhs)) {
+    if (m_has_val) {
+      expected_detail::construct_at(
+          std::addressof(m_val),
+          expected_detail::expected_source_value(std::forward<Rhs>(rhs)));
+    } else {
+      expected_detail::construct_at(
+          std::addressof(m_unexpect),
+          expected_detail::expected_source_error(std::forward<Rhs>(rhs)));
+    }
+  }
+
+  template <class... Args,
+            std::enable_if_t<std::is_constructible_v<T, Args&&...>>* = nullptr>
+  constexpr explicit storage_base(std::in_place_t, Args&&... args) noexcept(
+      noexcept(T(std::forward<Args>(args)...)))
+      : m_val(std::forward<Args>(args)...), m_has_val(true) {}
+
+  template <class U, class... Args,
+            std::enable_if_t<std::is_constructible_v<T, std::initializer_list<U>&,
+                                                     Args&&...>>* = nullptr>
+  constexpr explicit storage_base(
+      std::in_place_t, std::initializer_list<U> il,
+      Args&&... args) noexcept(noexcept(T(il, std::forward<Args>(args)...)))
+      : m_val(il, std::forward<Args>(args)...), m_has_val(true) {}
+
+  template <class... Args,
+            std::enable_if_t<std::is_constructible_v<E, Args&&...>>* = nullptr>
+  constexpr explicit storage_base(unexpect_t, Args&&... args) noexcept(
+      noexcept(E(std::forward<Args>(args)...)))
+      : m_unexpect(std::forward<Args>(args)...), m_has_val(false) {}
+
+  template <class U, class... Args,
+            std::enable_if_t<std::is_constructible_v<E, std::initializer_list<U>&,
+                                                     Args&&...>>* = nullptr>
+  constexpr explicit storage_base(
+      unexpect_t, std::initializer_list<U> il,
+      Args&&... args) noexcept(noexcept(E(il, std::forward<Args>(args)...)))
+      : m_unexpect(il, std::forward<Args>(args)...), m_has_val(false) {}
+
+  // helper ctor for transform()
+  template <class Fn, class... Args>
+  constexpr explicit storage_base(
+      construct_with_invoke_result_t, Fn&& func,
+      Args&&... args) noexcept(noexcept(static_cast<T>(std::invoke(std::forward<Fn>(func),
+                                                                   std::forward<Args>(
+                                                                       args)...))))
+      : m_val(std::invoke(std::forward<Fn>(func), std::forward<Args>(args)...)),
+        m_has_val(true) {}
+
+  // helper ctor for transform_error()
+  template <class Fn, class... Args>
+  constexpr explicit storage_base(
+      construct_with_invoke_result_t, unexpect_t, Fn&& func,
+      Args&&... args) noexcept(noexcept(static_cast<E>(std::invoke(std::forward<Fn>(func),
+                                                                   std::forward<Args>(
+                                                                       args)...))))
+      : m_unexpect(std::invoke(std::forward<Fn>(func), std::forward<Args>(args)...)),
+        m_has_val(false) {}
+
+  ~storage_base() = default;
+
+  union {
+    T m_val;
+    E m_unexpect;
+    char m_dummy;
+  };
+  bool m_has_val;
+};
+
+template <class T, class E>
+struct storage_base<T, E, false> {
+  storage_base(storage_base const&) = default;
+  storage_base(storage_base&&) = default;
+  storage_base& operator=(storage_base const&) = default;
+  storage_base& operator=(storage_base&&) = default;
+
+  // iceberg: constrained so MSVC never instantiates T{} for a T without an
+  // accessible default constructor.
+  template <class U = T, std::enable_if_t<std::is_default_constructible_v<U>, int> = 0>
+  constexpr storage_base() noexcept(std::is_nothrow_default_constructible_v<U>)
+      : m_val(), m_has_val(true) {}
+
+  template <class Rhs>
+  constexpr storage_base(construct_from_expected_t, Rhs&& rhs) noexcept(
+      std::is_nothrow_constructible_v<
+          T, decltype(expected_detail::expected_source_value(std::declval<Rhs>()))> &&
+      std::is_nothrow_constructible_v<
+          E, decltype(expected_detail::expected_source_error(std::declval<Rhs>()))>)
+      : m_dummy(), m_has_val(expected_detail::expected_source_has_value(rhs)) {
+    if (m_has_val) {
+      expected_detail::construct_at(
+          std::addressof(m_val),
+          expected_detail::expected_source_value(std::forward<Rhs>(rhs)));
+    } else {
+      expected_detail::construct_at(
+          std::addressof(m_unexpect),
+          expected_detail::expected_source_error(std::forward<Rhs>(rhs)));
+    }
+  }
+
+  template <class... Args,
+            std::enable_if_t<std::is_constructible_v<T, Args&&...>>* = nullptr>
+  constexpr explicit storage_base(std::in_place_t, Args&&... args) noexcept(
+      noexcept(T(std::forward<Args>(args)...)))
+      : m_val(std::forward<Args>(args)...), m_has_val(true) {}
+
+  template <class U, class... Args,
+            std::enable_if_t<std::is_constructible_v<T, std::initializer_list<U>&,
+                                                     Args&&...>>* = nullptr>
+  constexpr explicit storage_base(
+      std::in_place_t, std::initializer_list<U> il,
+      Args&&... args) noexcept(noexcept(T(il, std::forward<Args>(args)...)))
+      : m_val(il, std::forward<Args>(args)...), m_has_val(true) {}
+
+  template <class... Args,
+            std::enable_if_t<std::is_constructible_v<E, Args&&...>>* = nullptr>
+  constexpr explicit storage_base(unexpect_t, Args&&... args) noexcept(
+      noexcept(E(std::forward<Args>(args)...)))
+      : m_unexpect(std::forward<Args>(args)...), m_has_val(false) {}
+
+  template <class U, class... Args,
+            std::enable_if_t<std::is_constructible_v<E, std::initializer_list<U>&,
+                                                     Args&&...>>* = nullptr>
+  constexpr explicit storage_base(
+      unexpect_t, std::initializer_list<U> il,
+      Args&&... args) noexcept(noexcept(E(il, std::forward<Args>(args)...)))
+      : m_unexpect(il, std::forward<Args>(args)...), m_has_val(false) {}
+
+  // helper ctor for transform()
+  template <class Fn, class... Args>
+  constexpr explicit storage_base(
+      construct_with_invoke_result_t, Fn&& func,
+      Args&&... args) noexcept(noexcept(static_cast<T>(std::invoke(std::forward<Fn>(func),
+                                                                   std::forward<Args>(
+                                                                       args)...))))
+      : m_val(std::invoke(std::forward<Fn>(func), std::forward<Args>(args)...)),
+        m_has_val(true) {}
+
+  // helper ctor for transform_error()
+  template <class Fn, class... Args>
+  constexpr explicit storage_base(
+      construct_with_invoke_result_t, unexpect_t, Fn&& func,
+      Args&&... args) noexcept(noexcept(static_cast<E>(std::invoke(std::forward<Fn>(func),
+                                                                   std::forward<Args>(
+                                                                       args)...))))
+      : m_unexpect(std::invoke(std::forward<Fn>(func), std::forward<Args>(args)...)),
+        m_has_val(false) {}
+
+  // Keep the exception specification implicit; an explicit noexcept trips
+  // Clang's LLVM-59854 during constexpr destruction.
+  ICEBERG_EXPECTED_CONSTEXPR_DTOR ~storage_base() {
+    if (m_has_val) {
+      if constexpr (!std::is_trivially_destructible_v<T>) {
+        m_val.~T();
+      }
+    } else {
+      if constexpr (!std::is_trivially_destructible_v<E>) {
+        m_unexpect.~E();
+      }
+    }
+  }
+
+  union {
+    T m_val;
+    E m_unexpect;
+    char m_dummy;
+  };
+  bool m_has_val;
+};
+
+// `T` is `void`, `E` is trivially-destructible
+template <class E>
+struct storage_base<void, E, true> {
+  storage_base(storage_base const&) = default;
+  storage_base(storage_base&&) = default;
+  storage_base& operator=(storage_base const&) = default;
+  storage_base& operator=(storage_base&&) = default;
+
+  constexpr storage_base() noexcept : m_has_val(true) {}
+
+  template <class Rhs>
+  constexpr storage_base(construct_from_expected_t, Rhs&& rhs) noexcept(
+      std::is_nothrow_constructible_v<
+          E, decltype(expected_detail::expected_source_error(std::declval<Rhs>()))>)
+      : m_val(), m_has_val(expected_detail::expected_source_has_value(rhs)) {
+    if (!m_has_val) {
+      expected_detail::construct_at(
+          std::addressof(m_unexpect),
+          expected_detail::expected_source_error(std::forward<Rhs>(rhs)));
+    }
+  }
+
+  constexpr explicit storage_base(std::in_place_t) noexcept : m_has_val(true) {}
+
+  template <class... Args,
+            std::enable_if_t<std::is_constructible_v<E, Args&&...>>* = nullptr>
+  constexpr explicit storage_base(unexpect_t, Args&&... args)
+      : m_unexpect(std::forward<Args>(args)...), m_has_val(false) {}
+
+  template <class U, class... Args,
+            std::enable_if_t<std::is_constructible_v<E, std::initializer_list<U>&,
+                                                     Args&&...>>* = nullptr>
+  constexpr explicit storage_base(unexpect_t, std::initializer_list<U> il, Args&&... args)
+      : m_unexpect(il, std::forward<Args>(args)...), m_has_val(false) {}
+
+  // helper ctor for transform_error()
+  template <class Fn, class... Args>
+  constexpr explicit storage_base(
+      construct_with_invoke_result_t, unexpect_t, Fn&& func,
+      Args&&... args) noexcept(noexcept(static_cast<E>(std::invoke(std::forward<Fn>(func),
+                                                                   std::forward<Args>(
+                                                                       args)...))))
+      : m_unexpect(std::invoke(std::forward<Fn>(func), std::forward<Args>(args)...)),
+        m_has_val(false) {}
+
+  ~storage_base() = default;
+
+  struct dummy {};
+
+  union {
+    E m_unexpect;
+    dummy m_val;
+  };
+
+  bool m_has_val;
+};
+
+// `T` is `void`, `E` is not trivially-destructible
+template <class E>
+struct storage_base<void, E, false> {
+  storage_base(storage_base const&) = default;
+  storage_base(storage_base&&) = default;
+  storage_base& operator=(storage_base const&) = default;
+  storage_base& operator=(storage_base&&) = default;
+
+  constexpr storage_base() noexcept : m_has_val(true) {}
+
+  template <class Rhs>
+  constexpr storage_base(construct_from_expected_t, Rhs&& rhs) noexcept(
+      std::is_nothrow_constructible_v<
+          E, decltype(expected_detail::expected_source_error(std::declval<Rhs>()))>)
+      : m_val(), m_has_val(expected_detail::expected_source_has_value(rhs)) {
+    if (!m_has_val) {
+      expected_detail::construct_at(
+          std::addressof(m_unexpect),
+          expected_detail::expected_source_error(std::forward<Rhs>(rhs)));
+    }
+  }
+
+  constexpr explicit storage_base(std::in_place_t) noexcept : m_has_val(true) {}
+
+  template <class... Args,
+            std::enable_if_t<std::is_constructible_v<E, Args&&...>>* = nullptr>
+  constexpr explicit storage_base(unexpect_t, Args&&... args)
+      : m_unexpect(std::forward<Args>(args)...), m_has_val(false) {}
+
+  template <class U, class... Args,
+            std::enable_if_t<std::is_constructible_v<E, std::initializer_list<U>&,
+                                                     Args&&...>>* = nullptr>
+  constexpr explicit storage_base(unexpect_t, std::initializer_list<U> il, Args&&... args)
+      : m_unexpect(il, std::forward<Args>(args)...), m_has_val(false) {}
+
+  // helper ctor for transform_error()
+  template <class Fn, class... Args>
+  constexpr explicit storage_base(
+      construct_with_invoke_result_t, unexpect_t, Fn&& func,
+      Args&&... args) noexcept(noexcept(static_cast<E>(std::invoke(std::forward<Fn>(func),
+                                                                   std::forward<Args>(
+                                                                       args)...))))
+      : m_unexpect(std::invoke(std::forward<Fn>(func), std::forward<Args>(args)...)),
+        m_has_val(false) {}
+
+  // Keep the exception specification implicit; an explicit noexcept trips
+  // Clang's LLVM-59854 during constexpr destruction.
+  ICEBERG_EXPECTED_CONSTEXPR_DTOR ~storage_base() {
+    if (!m_has_val) {
+      m_unexpect.~E();
+    }
+  }
+
+  struct dummy {};
+
+  union {
+    E m_unexpect;
+    dummy m_val;
+  };
+
+  bool m_has_val;
+};
+
+// This base class provides some handy member functions which can be used in
+// further derived classes
+template <class T, class E>
+struct operations_base : storage_base<T, E> {
+  using storage_base<T, E>::storage_base;
+
+  constexpr T& get() & noexcept { return this->m_val; }
+  constexpr const T& get() const& noexcept { return this->m_val; }
+  constexpr T&& get() && noexcept(std::is_nothrow_move_constructible_v<T>) {
+    return std::move(this->m_val);
+  }
+  constexpr const T&& get() const&& noexcept(std::is_nothrow_move_constructible_v<T>) {
+    return std::move(this->m_val);
+  }
+
+  constexpr E& geterr() & noexcept { return this->m_unexpect; }
+  constexpr const E& geterr() const& noexcept { return this->m_unexpect; }
+  constexpr E&& geterr() && noexcept(std::is_nothrow_move_constructible_v<E>) {
+    return std::move(this->m_unexpect);
+  }
+  constexpr const E&& geterr() const&& noexcept(std::is_nothrow_move_constructible_v<E>) {
+    return std::move(this->m_unexpect);
+  }
+};
+
+// This base class provides some handy member functions which can be used in
+// further derived classes
+template <class E>
+struct operations_base<void, E> : storage_base<void, E> {
+  using storage_base<void, E>::storage_base;
+
+  constexpr E& geterr() & noexcept { return this->m_unexpect; }
+  constexpr const E& geterr() const& noexcept { return this->m_unexpect; }
+  constexpr E&& geterr() && noexcept(std::is_nothrow_move_constructible_v<E>) {
+    return std::move(this->m_unexpect);
+  }
+  constexpr const E&& geterr() const&& noexcept(std::is_nothrow_move_constructible_v<E>) {
+    return std::move(this->m_unexpect);
+  }
+};
+
+// This class manages conditionally having a trivial copy constructor
+// This specialization is for when T and E are trivially copy constructible
+template <class T, class E,
+          bool Enabled =
+              is_copy_constructible_or_void_v<T> && std::is_copy_constructible_v<E>,
+          bool Trivially = is_trivially_copy_constructible_or_void_v<T> &&
+                           std::is_trivially_copy_constructible_v<E>>
+struct copy_ctor_base : operations_base<T, E> {
+  using operations_base<T, E>::operations_base;
+};
+
+// This specialization is for when T or E are not copy constructible
+template <class T, class E>
+struct copy_ctor_base<T, E, false, false> : operations_base<T, E> {
+  using operations_base<T, E>::operations_base;
+
+  ~copy_ctor_base() = default;
+  copy_ctor_base() = default;
+  copy_ctor_base(const copy_ctor_base& rhs) = delete;
+  copy_ctor_base(copy_ctor_base&& rhs) = default;
+  copy_ctor_base& operator=(const copy_ctor_base& rhs) = default;
+  copy_ctor_base& operator=(copy_ctor_base&& rhs) = default;
+};
+
+// This specialization is for when T or E are not trivially copy constructible
+template <class T, class E>
+struct copy_ctor_base<T, E, true, false> : operations_base<T, E> {
+  using operations_base<T, E>::operations_base;
+
+  ~copy_ctor_base() = default;
+  copy_ctor_base() = default;
+
+  constexpr copy_ctor_base(const copy_ctor_base& rhs) noexcept(
+      is_nothrow_copy_constructible_or_void_v<T> &&
+      std::is_nothrow_copy_constructible_v<E>)
+      : operations_base<T, E>(construct_from_expected, rhs) {}
+
+  copy_ctor_base(copy_ctor_base&& rhs) = default;
+  copy_ctor_base& operator=(const copy_ctor_base& rhs) = default;
+  copy_ctor_base& operator=(copy_ctor_base&& rhs) = default;
+};
+
+// This class manages conditionally having a trivial move constructor
+template <class T, class E,
+          bool Enabled =
+              is_move_constructible_or_void_v<T> && std::is_move_constructible_v<E>,
+          bool Trivially = is_trivially_move_constructible_or_void_v<T> &&
+                           std::is_trivially_move_constructible_v<E>>
+struct move_ctor_base : copy_ctor_base<T, E> {
+  using copy_ctor_base<T, E>::copy_ctor_base;
+};
+
+// This specialization is for when T or E are not move constructible
+template <class T, class E>
+struct move_ctor_base<T, E, false, false> : copy_ctor_base<T, E> {
+  using copy_ctor_base<T, E>::copy_ctor_base;
+
+  ~move_ctor_base() = default;
+  move_ctor_base() = default;
+  move_ctor_base(const move_ctor_base& rhs) = default;
+  move_ctor_base(move_ctor_base&& rhs) = delete;
+  move_ctor_base& operator=(const move_ctor_base& rhs) = default;
+  move_ctor_base& operator=(move_ctor_base&& rhs) = default;
+};
+
+// This specialization is for when T or E are not trivially move constructible
+template <class T, class E>
+struct move_ctor_base<T, E, true, false> : copy_ctor_base<T, E> {
+  using copy_ctor_base<T, E>::copy_ctor_base;
+
+  ~move_ctor_base() = default;
+  move_ctor_base() = default;
+  move_ctor_base(const move_ctor_base& rhs) = default;
+
+  constexpr move_ctor_base(move_ctor_base&& rhs) noexcept(
+      is_nothrow_move_constructible_or_void_v<T> &&
+      std::is_nothrow_move_constructible_v<E>)
+      : copy_ctor_base<T, E>(construct_from_expected, std::move(rhs)) {}
+
+  move_ctor_base& operator=(const move_ctor_base& rhs) = default;
+  move_ctor_base& operator=(move_ctor_base&& rhs) = default;
+};
+
+template <class T, class E>
+inline constexpr bool is_expected_copy_assignable_v =
+    is_copy_assignable_or_void_v<T> && is_copy_constructible_or_void_v<T> &&
+    std::is_copy_assignable_v<E> && std::is_copy_constructible_v<E> &&
+    (is_nothrow_move_constructible_or_void_v<T> ||
+     std::is_nothrow_move_constructible_v<E>);
+
+// LWG-4026
+template <class T, class E>
+inline constexpr bool is_expected_trivially_copy_assignable_v =
+    is_trivially_copy_constructible_or_void_v<T> &&
+    is_trivially_copy_assignable_or_void_v<T> && is_trivially_destructible_or_void_v<T> &&
+    std::is_trivially_copy_constructible_v<E> && std::is_trivially_copy_assignable_v<E> &&
+    std::is_trivially_destructible_v<E>;
+
+// This class manages conditionally having a (possibly trivial) copy assignment operator
+template <class T, class E, bool Enabled = is_expected_copy_assignable_v<T, E>,
+          bool Trivially = is_expected_trivially_copy_assignable_v<T, E>>
+struct copy_assign_base : move_ctor_base<T, E> {
+  using move_ctor_base<T, E>::move_ctor_base;
+
+  ~copy_assign_base() = default;
+  copy_assign_base() = default;
+  copy_assign_base(const copy_assign_base& rhs) = default;
+  copy_assign_base(copy_assign_base&& rhs) = default;
+  copy_assign_base& operator=(const copy_assign_base& rhs) = default;
+  copy_assign_base& operator=(copy_assign_base&& rhs) = default;
+};
+
+template <class T, class E>
+struct copy_assign_base<T, E, false, false> : move_ctor_base<T, E> {
+  using move_ctor_base<T, E>::move_ctor_base;
+
+  ~copy_assign_base() = default;
+  copy_assign_base() = default;
+  copy_assign_base(const copy_assign_base& rhs) = default;
+  copy_assign_base(copy_assign_base&& rhs) = default;
+  copy_assign_base& operator=(const copy_assign_base& rhs) = delete;
+  copy_assign_base& operator=(copy_assign_base&& rhs) = default;
+};
+
+template <class T, class E>
+struct copy_assign_base<T, E, true, false> : move_ctor_base<T, E> {
+  using move_ctor_base<T, E>::move_ctor_base;
+
+  ~copy_assign_base() = default;
+  copy_assign_base() = default;
+  copy_assign_base(const copy_assign_base& rhs) = default;
+  copy_assign_base(copy_assign_base&& rhs) = default;
+
+  constexpr copy_assign_base& operator=(const copy_assign_base& rhs) noexcept(
+      std::is_nothrow_copy_constructible_v<T> && std::is_nothrow_copy_assignable_v<T> &&
+      std::is_nothrow_copy_constructible_v<E> && std::is_nothrow_copy_assignable_v<E>) {
+    if (this->m_has_val && rhs.m_has_val) {
+      this->m_val = rhs.m_val;
+    } else if (this->m_has_val) {
+      expected_detail::reinit_expected(this->m_unexpect, this->m_val, rhs.m_unexpect);
+    } else if (rhs.m_has_val) {
+      expected_detail::reinit_expected(this->m_val, this->m_unexpect, rhs.m_val);
+    } else {
+      this->m_unexpect = rhs.m_unexpect;
+    }
+    this->m_has_val = rhs.m_has_val;
+    return *this;
+  }
+
+  copy_assign_base& operator=(copy_assign_base&& rhs) = default;
+};
+
+template <class E>
+struct copy_assign_base<void, E, true, false> : move_ctor_base<void, E> {
+  using move_ctor_base<void, E>::move_ctor_base;
+
+  ~copy_assign_base() = default;
+  copy_assign_base() = default;
+  copy_assign_base(const copy_assign_base& rhs) = default;
+  copy_assign_base(copy_assign_base&& rhs) = default;
+
+  constexpr copy_assign_base& operator=(const copy_assign_base& rhs) noexcept(
+      std::is_nothrow_copy_constructible_v<E> && std::is_nothrow_copy_assignable_v<E>) {
+    if (this->m_has_val && rhs.m_has_val) {
+      // no-op
+    } else if (this->m_has_val) {
+      expected_detail::construct_at(std::addressof(this->m_unexpect), rhs.m_unexpect);
+      this->m_has_val = false;
+    } else if (rhs.m_has_val) {
+      this->m_unexpect.~E();
+      this->m_has_val = true;
+    } else {
+      this->m_unexpect = rhs.m_unexpect;
+    }
+    return *this;
+  }
+
+  copy_assign_base& operator=(copy_assign_base&& rhs) = default;
+};
+
+template <class T, class E>
+inline constexpr bool is_expected_move_assignable_v =
+    is_move_assignable_or_void_v<T> && is_move_constructible_or_void_v<T> &&
+    std::is_move_assignable_v<E> && std::is_move_constructible_v<E> &&
+    (is_nothrow_move_constructible_or_void_v<T> ||
+     std::is_nothrow_move_constructible_v<E>);
+
+// LWG-4026
+template <class T, class E>
+inline constexpr bool is_expected_trivially_move_assignable_v =
+    is_trivially_move_constructible_or_void_v<T> &&
+    is_trivially_move_assignable_or_void_v<T> && is_trivially_destructible_or_void_v<T> &&
+    std::is_trivially_move_constructible_v<E> && std::is_trivially_move_assignable_v<E> &&
+    std::is_trivially_destructible_v<E>;
+
+// This class manages conditionally having a (possibly trivial) move assignment operator
+template <class T, class E, bool Enabled = is_expected_move_assignable_v<T, E>,
+          bool Trivially = is_expected_trivially_move_assignable_v<T, E>>
+struct move_assign_base : copy_assign_base<T, E> {
+  using copy_assign_base<T, E>::copy_assign_base;
+
+  ~move_assign_base() = default;
+  move_assign_base() = default;
+  move_assign_base(const move_assign_base& rhs) = default;
+  move_assign_base(move_assign_base&& rhs) = default;
+  move_assign_base& operator=(const move_assign_base& rhs) = default;
+  move_assign_base& operator=(move_assign_base&& rhs) = default;
+};
+
+template <class T, class E>
+struct move_assign_base<T, E, false, false> : copy_assign_base<T, E> {
+  using copy_assign_base<T, E>::copy_assign_base;
+
+  ~move_assign_base() = default;
+  move_assign_base() = default;
+  move_assign_base(const move_assign_base& rhs) = default;
+  move_assign_base(move_assign_base&& rhs) = default;
+  move_assign_base& operator=(const move_assign_base& rhs) = default;
+  move_assign_base& operator=(move_assign_base&& rhs) = delete;
+};
+
+template <class T, class E>
+struct move_assign_base<T, E, true, false> : copy_assign_base<T, E> {
+  using copy_assign_base<T, E>::copy_assign_base;
+
+  ~move_assign_base() = default;
+  move_assign_base() = default;
+  move_assign_base(const move_assign_base& rhs) = default;
+  move_assign_base(move_assign_base&& rhs) = default;
+  move_assign_base& operator=(const move_assign_base& rhs) = default;
+
+  constexpr move_assign_base& operator=(move_assign_base&& rhs) noexcept(
+      std::is_nothrow_move_constructible_v<T> && std::is_nothrow_move_assignable_v<T> &&
+      std::is_nothrow_move_constructible_v<E> && std::is_nothrow_move_assignable_v<E>) {
+    if (this->m_has_val && rhs.m_has_val) {
+      this->m_val = std::move(rhs.m_val);
+    } else if (this->m_has_val) {
+      expected_detail::reinit_expected(this->m_unexpect, this->m_val,
+                                       std::move(rhs.m_unexpect));
+    } else if (rhs.m_has_val) {
+      expected_detail::reinit_expected(this->m_val, this->m_unexpect,
+                                       std::move(rhs.m_val));
+    } else {
+      this->m_unexpect = std::move(rhs.m_unexpect);
+    }
+    this->m_has_val = rhs.m_has_val;
+    return *this;
+  }
+};
+
+template <class E>
+struct move_assign_base<void, E, true, false> : copy_assign_base<void, E> {
+  using copy_assign_base<void, E>::copy_assign_base;
+
+  ~move_assign_base() = default;
+  move_assign_base() = default;
+  move_assign_base(const move_assign_base& rhs) = default;
+  move_assign_base(move_assign_base&& rhs) = default;
+  move_assign_base& operator=(const move_assign_base& rhs) = default;
+
+  constexpr move_assign_base& operator=(move_assign_base&& rhs) noexcept(
+      std::is_nothrow_move_constructible_v<E> && std::is_nothrow_move_assignable_v<E>) {
+    if (this->m_has_val && rhs.m_has_val) {
+      // no-op
+    } else if (this->m_has_val) {
+      expected_detail::construct_at(std::addressof(this->m_unexpect),
+                                    std::move(rhs.m_unexpect));
+      this->m_has_val = false;
+    } else if (rhs.m_has_val) {
+      this->m_unexpect.~E();
+      this->m_has_val = true;
+    } else {
+      this->m_unexpect = std::move(rhs.m_unexpect);
+    }
+    return *this;
+  }
+};
+
+// This is needed to be able to construct the default_ctor_base which
+// follows, while still conditionally deleting the default constructor.
+struct default_constructor_tag {
+  explicit default_constructor_tag() = default;
+};
+
+// default_ctor_base will ensure that expected has a deleted default
+// consturctor if T is not default constructible.
+// This specialization is for when T is default constructible
+template <class T, class E, bool Enable = is_default_constructible_or_void_v<T>>
+struct default_ctor_base {
+  ~default_ctor_base() = default;
+  default_ctor_base() = default;
+  default_ctor_base(default_ctor_base const&) = default;
+  default_ctor_base(default_ctor_base&&) = default;
+  default_ctor_base& operator=(default_ctor_base const&) = default;
+  default_ctor_base& operator=(default_ctor_base&&) = default;
+
+  constexpr explicit default_ctor_base(default_constructor_tag) {}
+};
+
+// This specialization is for when T is not default constructible
+template <class T, class E>
+struct default_ctor_base<T, E, false> {
+  ~default_ctor_base() = default;
+  default_ctor_base() = delete;
+  default_ctor_base(default_ctor_base const&) = default;
+  default_ctor_base(default_ctor_base&&) = default;
+  default_ctor_base& operator=(default_ctor_base const&) = default;
+  default_ctor_base& operator=(default_ctor_base&&) = default;
+
+  constexpr explicit default_ctor_base(default_constructor_tag) {}
+};
+
+}  // namespace expected_detail
+
+/// An `expected<T, E>` object is an object that contains the storage for
+/// another object and manages the lifetime of this contained object `T`.
+/// Alternatively it could contain the storage for another unexpected object
+/// `E`. The contained object may not be initialized after the expected object
+/// has been initialized, and may not be destroyed before the expected object
+/// has been destroyed. The initialization state of the contained object is
+/// tracked by the expected object.
+template <class T, class E>
+class ICEBERG_TEMPLATE_CLASS_EXPORT [[nodiscard]] expected
+    : private expected_detail::move_assign_base<T, E>,
+      private expected_detail::default_ctor_base<T, E> {
+  static_assert(expected_detail::is_value_type_valid_v<T>);
+  static_assert(expected_detail::is_error_type_valid_v<E>);
+
+  constexpr T* valptr() noexcept { return std::addressof(this->m_val); }
+  constexpr const T* valptr() const noexcept { return std::addressof(this->m_val); }
+  constexpr E* errptr() noexcept { return std::addressof(this->m_unexpect); }
+  constexpr const E* errptr() const noexcept { return std::addressof(this->m_unexpect); }
+
+  constexpr T& val() noexcept { return this->m_val; }
+  constexpr E& err() noexcept { return this->m_unexpect; }
+
+  constexpr const T& val() const noexcept { return this->m_val; }
+  constexpr const E& err() const noexcept { return this->m_unexpect; }
+
+  using impl_base = expected_detail::move_assign_base<T, E>;
+  using ctor_base = expected_detail::default_ctor_base<T, E>;
+
+ public:
+  typedef T value_type;
+  typedef E error_type;
+  typedef unexpected<E> unexpected_type;
+
+  template <class U>
+  using rebind = expected<U, error_type>;
+
+  // default constructors
+
+  constexpr expected() = default;
+  constexpr expected(const expected& rhs) = default;
+  constexpr expected(expected&& rhs) = default;
+
+  // constructors for expected<U, G>
+
+  // implicit const reference
+  template <class U, class G,
+            std::enable_if_t<!std::is_same_v<expected<U, G>, expected>>* = nullptr,
+            std::enable_if_t<std::is_convertible_v<const U&, T> &&
+                             std::is_convertible_v<const G&, E>>* = nullptr,
+            expected_detail::enable_from_other_expected_t<T, E, U, G, const U&,
+                                                          const G&>* = nullptr>
+  constexpr expected(const expected<U, G>& rhs) noexcept(
+      std::is_nothrow_constructible_v<T, const U&> &&
+      std::is_nothrow_constructible_v<E, const G&>)
+      : impl_base(expected_detail::construct_from_expected, rhs),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // explicit const reference
+  template <class U, class G,
+            std::enable_if_t<!std::is_same_v<expected<U, G>, expected>>* = nullptr,
+            std::enable_if_t<!(std::is_convertible_v<const U&, T> &&
+                               std::is_convertible_v<const G&, E>)>* = nullptr,
+            expected_detail::enable_from_other_expected_t<T, E, U, G, const U&,
+                                                          const G&>* = nullptr>
+  constexpr explicit expected(const expected<U, G>& rhs) noexcept(
+      std::is_nothrow_constructible_v<T, const U&> &&
+      std::is_nothrow_constructible_v<E, const G&>)
+      : impl_base(expected_detail::construct_from_expected, rhs),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // implicit rvalue
+  template <class U, class G,
+            std::enable_if_t<!std::is_same_v<expected<U, G>, expected>>* = nullptr,
+            std::enable_if_t<std::is_convertible_v<U, T> &&
+                             std::is_convertible_v<G, E>>* = nullptr,
+            expected_detail::enable_from_other_expected_t<T, E, U, G, U, G>* = nullptr>
+  constexpr expected(expected<U, G>&& rhs) noexcept(
+      std::is_nothrow_constructible_v<T, U> && std::is_nothrow_constructible_v<E, G>)
+      : impl_base(expected_detail::construct_from_expected, std::move(rhs)),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // explicit rvalue
+  template <class U, class G,
+            std::enable_if_t<!std::is_same_v<expected<U, G>, expected>>* = nullptr,
+            std::enable_if_t<!(std::is_convertible_v<U, T> &&
+                               std::is_convertible_v<G, E>)>* = nullptr,
+            expected_detail::enable_from_other_expected_t<T, E, U, G, U, G>* = nullptr>
+  constexpr explicit expected(expected<U, G>&& rhs) noexcept(
+      std::is_nothrow_constructible_v<T, U> && std::is_nothrow_constructible_v<E, G>)
+      : impl_base(expected_detail::construct_from_expected, std::move(rhs)),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // template <class U = T>
+  //     expected(U &&)
+
+  // implicit
+  template <class U = std::remove_cv_t<T>,
+            std::enable_if_t<std::is_convertible_v<U, T>>* = nullptr,
+            expected_detail::enable_forward_t<T, E, U>* = nullptr>
+  constexpr expected(U&& v) noexcept(std::is_nothrow_constructible_v<T, U>)
+      : expected(std::in_place, std::forward<U>(v)) {}
+
+  // explicit
+  template <class U = std::remove_cv_t<T>,
+            std::enable_if_t<!std::is_convertible_v<U, T>>* = nullptr,
+            expected_detail::enable_forward_t<T, E, U>* = nullptr>
+  constexpr explicit expected(U&& v) noexcept(std::is_nothrow_constructible_v<T, U>)
+      : expected(std::in_place, std::forward<U>(v)) {}
+
+#if defined(__cpp_lib_expected) && __cpp_lib_expected >= 202202L
+  // iceberg: library code built as C++23 still spells some errors std::unexpected.
+  template <class G, std::enable_if_t<std::is_constructible_v<E, const G&>>* = nullptr>
+  constexpr explicit(!std::is_convertible_v<const G&, E>) expected(
+      const std::unexpected<G>& e) noexcept(std::is_nothrow_constructible_v<E, const G&>)
+      : expected(unexpect, e.error()) {}
+
+  template <class G, std::enable_if_t<std::is_constructible_v<E, G>>* = nullptr>
+  constexpr explicit(!std::is_convertible_v<G, E>)
+      expected(std::unexpected<G>&& e) noexcept(std::is_nothrow_constructible_v<E, G>)
+      : expected(unexpect, std::move(e.error())) {}
+#endif
+
+  // constructors for unexpected<G>
+
+  // explicit const unexpected<G> &
+  template <class G, std::enable_if_t<!std::is_convertible_v<const G&, E>>* = nullptr,
+            std::enable_if_t<std::is_constructible_v<E, const G&>>* = nullptr>
+  explicit constexpr expected(const unexpected<G>& e) noexcept(
+      std::is_nothrow_constructible_v<E, const G&>)
+      : impl_base(unexpect, e.error()),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // implicit const unexpected<G> &
+  template <class G, std::enable_if_t<std::is_convertible_v<const G&, E>>* = nullptr,
+            std::enable_if_t<std::is_constructible_v<E, const G&>>* = nullptr>
+  constexpr expected(unexpected<G> const& e) noexcept(
+      std::is_nothrow_constructible_v<E, const G&>)
+      : impl_base(unexpect, e.error()),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // explicit unexpected<G> &&
+  template <class G, std::enable_if_t<!std::is_convertible_v<G, E>>* = nullptr,
+            std::enable_if_t<std::is_constructible_v<E, G>>* = nullptr>
+  explicit constexpr expected(unexpected<G>&& e) noexcept(
+      std::is_nothrow_constructible_v<E, G>)
+      : impl_base(unexpect, std::move(e.error())),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // implicit unexpected<G> &&
+  template <class G, std::enable_if_t<std::is_convertible_v<G, E>>* = nullptr,
+            std::enable_if_t<std::is_constructible_v<E, G>>* = nullptr>
+  constexpr expected(unexpected<G>&& e) noexcept(std::is_nothrow_constructible_v<E, G>)
+      : impl_base(unexpect, std::move(e.error())),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // template<class... Args>
+  //     expected(std::in_place_t, Args &&...)
+
+  template <class... Args,
+            std::enable_if_t<std::is_constructible_v<T, Args...>>* = nullptr>
+  constexpr explicit expected(std::in_place_t, Args&&... args) noexcept(
+      std::is_nothrow_constructible_v<T, Args...>)
+      : impl_base(std::in_place, std::forward<Args>(args)...),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // template<class U, class... Args>
+  //     expected(std::in_place_t, std::initializer_list<U>, Args &&...)
+
+  template <class U, class... Args,
+            std::enable_if_t<std::is_constructible_v<T, std::initializer_list<U>&,
+                                                     Args...>>* = nullptr>
+  constexpr explicit expected(
+      std::in_place_t, std::initializer_list<U> il,
+      Args&&... args) noexcept(std::is_nothrow_constructible_v<T,
+                                                               std::initializer_list<U>&,
+                                                               Args...>)
+      : impl_base(std::in_place, il, std::forward<Args>(args)...),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // helper ctor for transform()
+  template <class Fn, class... Args>
+  constexpr explicit expected(
+      expected_detail::construct_with_invoke_result_t tag, Fn&& func,
+      Args&&... args) noexcept(noexcept(static_cast<T>(std::invoke(std::forward<Fn>(func),
+                                                                   std::forward<Args>(
+                                                                       args)...))))
+      : impl_base(tag, std::forward<Fn>(func), std::forward<Args>(args)...),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // template<class... Args>
+  //     expected(unexpect_t, Args &&...)
+
+  template <class... Args,
+            std::enable_if_t<std::is_constructible_v<E, Args...>>* = nullptr>
+  constexpr explicit expected(unexpect_t, Args&&... args) noexcept(
+      std::is_nothrow_constructible_v<E, Args...>)
+      : impl_base(unexpect, std::forward<Args>(args)...),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // template<class U, class... Args>
+  //     expected(unexpect_t, std::initializer_list<U>, Args &&...)
+
+  template <class U, class... Args,
+            std::enable_if_t<std::is_constructible_v<E, std::initializer_list<U>&,
+                                                     Args...>>* = nullptr>
+  constexpr explicit expected(
+      unexpect_t, std::initializer_list<U> il,
+      Args&&... args) noexcept(std::is_nothrow_constructible_v<E,
+                                                               std::initializer_list<U>&,
+                                                               Args...>)
+      : impl_base(unexpect, il, std::forward<Args>(args)...),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // helper ctor for transform_error()
+  template <class Fn, class... Args>
+  constexpr explicit expected(
+      expected_detail::construct_with_invoke_result_t tag1, unexpect_t tag2, Fn&& func,
+      Args&&... args) noexcept(noexcept(static_cast<E>(std::invoke(std::forward<Fn>(func),
+                                                                   std::forward<Args>(
+                                                                       args)...))))
+      : impl_base(tag1, tag2, std::forward<Fn>(func), std::forward<Args>(args)...),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // default assignment operators
+
+  constexpr expected& operator=(const expected& rhs) = default;
+  constexpr expected& operator=(expected&& rhs) = default;
+
+  // assignments
+
+  template <
+      class U = std::remove_cv_t<T>,
+      std::enable_if_t<!std::is_same_v<expected, expected_detail::remove_cvref_t<U>> &&
+                       !expected_detail::is_specialization_v<
+                           expected_detail::remove_cvref_t<U>, unexpected> &&
+                       std::is_constructible_v<T, U> && std::is_assignable_v<T&, U> &&
+                       (std::is_nothrow_constructible_v<T, U> ||
+                        std::is_nothrow_move_constructible_v<T> ||
+                        std::is_nothrow_move_constructible_v<E>)>* = nullptr>
+  constexpr expected& operator=(U&& v) noexcept(std::is_nothrow_constructible_v<T, U> &&
+                                                std::is_nothrow_assignable_v<T&, U>) {
+    if (has_value()) {
+      val() = std::forward<U>(v);
+    } else {
+      expected_detail::reinit_expected(val(), err(), std::forward<U>(v));
+      this->m_has_val = true;
+    }
+
+    return *this;
+  }
+
+  template <
+      class G, class GF = const G&,
+      std::enable_if_t<std::is_constructible_v<E, GF> && std::is_assignable_v<E&, GF> &&
+                       (std::is_nothrow_constructible_v<E, GF> ||
+                        std::is_nothrow_move_constructible_v<T> ||
+                        std::is_nothrow_move_constructible_v<E>)>* = nullptr>
+  constexpr expected& operator=(const unexpected<G>& rhs) noexcept(
+      std::is_nothrow_constructible_v<E, GF> && std::is_nothrow_assignable_v<E&, GF>) {
+    if (!has_value()) {
+      err() = std::forward<GF>(rhs.error());
+    } else {
+      expected_detail::reinit_expected(err(), val(), std::forward<GF>(rhs.error()));
+      this->m_has_val = false;
+    }
+
+    return *this;
+  }
+
+  template <
+      class G, class GF = G,
+      std::enable_if_t<std::is_constructible_v<E, GF> && std::is_assignable_v<E&, GF> &&
+                       (std::is_nothrow_constructible_v<E, GF> ||
+                        std::is_nothrow_move_constructible_v<T> ||
+                        std::is_nothrow_move_constructible_v<E>)>* = nullptr>
+  constexpr expected& operator=(unexpected<G>&& rhs) noexcept(
+      std::is_nothrow_constructible_v<E, GF> && std::is_nothrow_assignable_v<E&, GF>) {
+    if (!has_value()) {
+      err() = std::forward<GF>(rhs.error());
+    } else {
+      expected_detail::reinit_expected(err(), val(), std::forward<GF>(rhs.error()));
+      this->m_has_val = false;
+    }
+
+    return *this;
+  }
+
+  template <class... Args,
+            typename std::enable_if_t<std::is_nothrow_constructible_v<T, Args&&...>,
+                                      bool> = false>
+  constexpr T& emplace(Args&&... args) {
+    if (has_value()) {
+      if constexpr (!std::is_trivially_destructible_v<T>) {
+        val().~T();
+      }
+    } else {
+      if constexpr (!std::is_trivially_destructible_v<E>) {
+        err().~E();
+      }
+      this->m_has_val = true;
+    }
+
+    return *expected_detail::construct_at(valptr(), std::forward<Args>(args)...);
+  }
+
+  template <class U, class... Args,
+            std::enable_if_t<std::is_nothrow_constructible_v<T, std::initializer_list<U>&,
+                                                             Args&&...>>* = nullptr>
+  constexpr T& emplace(std::initializer_list<U> il, Args&&... args) {
+    if (has_value()) {
+      if constexpr (!std::is_trivially_destructible_v<T>) {
+        val().~T();
+      }
+    } else {
+      if constexpr (!std::is_trivially_destructible_v<E>) {
+        err().~E();
+      }
+      this->m_has_val = true;
+    }
+
+    return *expected_detail::construct_at(valptr(), il, std::forward<Args>(args)...);
+  }
+
+  template <class OT = T, class OE = E>
+  constexpr std::enable_if_t<std::is_swappable_v<OT> && std::is_swappable_v<OE> &&
+                             std::is_move_constructible_v<OT> &&
+                             std::is_move_constructible_v<OE> &&
+                             (std::is_nothrow_move_constructible_v<OT> ||
+                              std::is_nothrow_move_constructible_v<OE>)>
+  swap(expected& rhs) noexcept(std::is_nothrow_move_constructible_v<T> &&
+                               std::is_nothrow_swappable_v<T> &&
+                               std::is_nothrow_move_constructible_v<E> &&
+                               std::is_nothrow_swappable_v<E>) {
+    using std::swap;
+    if (this->m_has_val && rhs.m_has_val) {
+      swap(this->m_val, rhs.m_val);  // ADL
+    } else if (this->m_has_val) {
+      if constexpr (std::is_nothrow_move_constructible_v<E>) {
+        E tmp(std::move(rhs.error()));
+        if constexpr (!std::is_trivially_destructible_v<E>) {
+          rhs.error().~E();
+        }
+
+        if constexpr (std::is_nothrow_move_constructible_v<T>) {
+          expected_detail::construct_at(std::addressof(rhs.m_val),
+                                        std::move(this->m_val));
+        } else {
+          expected_detail::ReinitGuard<E> guard{std::addressof(rhs.error()),
+                                                std::addressof(tmp)};
+          expected_detail::construct_at(std::addressof(rhs.m_val),
+                                        std::move(this->m_val));
+          guard._target = nullptr;
+        }
+
+        if constexpr (!std::is_trivially_destructible_v<T>) {
+          this->m_val.~T();
+        }
+        expected_detail::construct_at(std::addressof(this->error()), std::move(tmp));
+      } else {
+        T tmp(std::move(this->m_val));
+        if constexpr (!std::is_trivially_destructible_v<T>) {
+          this->m_val.~T();
+        }
+
+        expected_detail::ReinitGuard<T> guard{std::addressof(this->m_val),
+                                              std::addressof(tmp)};
+        expected_detail::construct_at(std::addressof(this->error()),
+                                      std::move(rhs.error()));
+        guard._target = nullptr;
+
+        if constexpr (!std::is_trivially_destructible_v<E>) {
+          rhs.error().~E();
+        }
+        expected_detail::construct_at(std::addressof(rhs.m_val), std::move(tmp));
+      }
+
+      this->m_has_val = false;
+      rhs.m_has_val = true;
+    } else if (rhs.m_has_val) {
+      rhs.swap(*this);
+    } else {
+      swap(this->error(), rhs.error());  // ADL
+    }
+  }
+
+  constexpr const T* operator->() const noexcept { return valptr(); }
+  constexpr T* operator->() noexcept { return valptr(); }
+
+  constexpr const T& operator*() const& noexcept { return val(); }
+  constexpr T& operator*() & noexcept { return val(); }
+  constexpr const T&& operator*() const&& noexcept { return std::move(val()); }
+  constexpr T&& operator*() && noexcept { return std::move(val()); }
+
+  constexpr bool has_value() const noexcept { return this->m_has_val; }
+  constexpr explicit operator bool() const noexcept { return this->m_has_val; }
+
+  constexpr const T& value() const& {
+    static_assert(std::is_copy_constructible_v<E>,
+                  "E must be copy constructible, by LWG-3843");
+    if (!has_value()) ICEBERG_EXPECTED_THROW(bad_expected_access(error()));
+    return val();
+  }
+  constexpr T& value() & {
+    static_assert(std::is_copy_constructible_v<E>,
+                  "E must be copy constructible, by LWG-3843");
+    if (!has_value()) ICEBERG_EXPECTED_THROW(bad_expected_access(std::as_const(error())));
+    return val();
+  }
+  constexpr const T&& value() const&& {
+    static_assert(std::is_copy_constructible_v<E>,
+                  "E must be copy constructible, by LWG-3843");
+    static_assert(std::is_constructible_v<E, decltype(std::move(error()))>,
+                  "E must be constructible from const E&&, by LWG-3843");
+    if (!has_value()) ICEBERG_EXPECTED_THROW(bad_expected_access(std::move(error())));
+    return std::move(val());
+  }
+  constexpr T&& value() && {
+    static_assert(std::is_copy_constructible_v<E>,
+                  "E must be copy constructible, by LWG-3843");
+    static_assert(std::is_constructible_v<E, decltype(std::move(error()))>,
+                  "E must be constructible from E&&, by LWG-3843");
+    if (!has_value()) ICEBERG_EXPECTED_THROW(bad_expected_access(std::move(error())));
+    return std::move(val());
+  }
+
+  constexpr const E& error() const& noexcept { return err(); }
+  constexpr E& error() & noexcept { return err(); }
+  constexpr const E&& error() const&& noexcept { return std::move(err()); }
+  constexpr E&& error() && noexcept { return std::move(err()); }
+
+  template <class U = std::remove_cv_t<T>>
+  constexpr T value_or(U&& v) const& noexcept(
+      std::is_nothrow_copy_constructible_v<T> &&
+      expected_detail::is_nothrow_convertible_v<U, T>) {
+    static_assert(std::is_copy_constructible_v<T>, "T must be copy-constructible");
+    static_assert(std::is_convertible_v<U, T>, "is_convertible_v<U, T> must be true");
+    if (this->m_has_val) {
+      return this->m_val;
+    } else {
+      return static_cast<T>(std::forward<U>(v));
+    }
+  }
+  template <class U = std::remove_cv_t<T>>
+  constexpr T value_or(U&& v) && noexcept(
+      std::is_nothrow_move_constructible_v<T> &&
+      expected_detail::is_nothrow_convertible_v<U, T>) {
+    static_assert(std::is_move_constructible_v<T>, "T must be move-constructible");
+    static_assert(std::is_convertible_v<U, T>, "is_convertible_v<U, T> must be true");
+    if (this->m_has_val) {
+      return std::move(this->m_val);
+    } else {
+      return static_cast<T>(std::forward<U>(v));
+    }
+  }
+
+  template <class G = E>
+  constexpr E error_or(G&& v) const& noexcept(
+      std::is_nothrow_copy_constructible_v<E> &&
+      expected_detail::is_nothrow_convertible_v<G, E>) {
+    static_assert(std::is_copy_constructible_v<E>, "E must be copy-constructible");
+    static_assert(std::is_convertible_v<G, E>, "is_convertible_v<G, E> must be true");
+    if (this->m_has_val) {
+      return static_cast<E>(std::forward<G>(v));
+    } else {
+      return this->m_unexpect;
+    }
+  }
+  template <class G = E>
+  constexpr E error_or(G&& v) && noexcept(
+      std::is_nothrow_move_constructible_v<E> &&
+      expected_detail::is_nothrow_convertible_v<G, E>) {
+    static_assert(std::is_move_constructible_v<E>, "E must be move-constructible");
+    static_assert(std::is_convertible_v<G, E>, "is_convertible_v<G, E> must be true");
+    if (this->m_has_val) {
+      return static_cast<E>(std::forward<G>(v));
+    } else {
+      return std::move(this->m_unexpect);
+    }
+  }
+
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, GE&>>* = nullptr>
+  constexpr auto and_then(F&& f) & {
+    using U =
+        expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype((this->m_val))>>;
+    static_assert(expected_detail::is_specialization_v<U, expected>,
+                  "U (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename U::error_type, E>,
+                  "The error type must be the same after calling the F");
+
+    if (has_value())
+      return std::invoke(std::forward<F>(f), this->m_val);
+    else
+      return U(unexpect, error());
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, const GE&>>* = nullptr>
+  constexpr auto and_then(F&& f) const& {
+    using U =
+        expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype((this->m_val))>>;
+    static_assert(expected_detail::is_specialization_v<U, expected>,
+                  "U (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename U::error_type, E>,
+                  "The error type must be the same after calling the F");
+
+    if (has_value())
+      return std::invoke(std::forward<F>(f), this->m_val);
+    else
+      return U(unexpect, error());
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, GE&&>>* = nullptr>
+  constexpr auto and_then(F&& f) && {
+    using U = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(this->m_val))>>;
+    static_assert(expected_detail::is_specialization_v<U, expected>,
+                  "U (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename U::error_type, E>,
+                  "The error type must be the same after calling the F");
+
+    if (has_value())
+      return std::invoke(std::forward<F>(f), std::move(this->m_val));
+    else
+      return U(unexpect, std::move(error()));
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, const GE>>* = nullptr>
+  constexpr auto and_then(F&& f) const&& {
+    using U = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(this->m_val))>>;
+    static_assert(expected_detail::is_specialization_v<U, expected>,
+                  "U (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename U::error_type, E>,
+                  "The error type must be the same after calling the F");
+
+    if (has_value())
+      return std::invoke(std::forward<F>(f), std::move(this->m_val));
+    else
+      return U(unexpect, std::move(error()));
+  }
+
+  template <class F, class UT = T,
+            std::enable_if_t<std::is_constructible_v<UT, UT&>>* = nullptr>
+  constexpr auto or_else(F&& f) & {
+    using G = expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype(error())>>;
+    static_assert(expected_detail::is_specialization_v<G, expected>,
+                  "G (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename G::value_type, T>,
+                  "The value type must be the same after calling the F");
+
+    if (has_value())
+      return G(std::in_place, this->m_val);
+    else
+      return std::invoke(std::forward<F>(f), error());
+  }
+  template <class F, class UT = T,
+            std::enable_if_t<std::is_constructible_v<UT, const UT&>>* = nullptr>
+  constexpr auto or_else(F&& f) const& {
+    using G = expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype(error())>>;
+    static_assert(expected_detail::is_specialization_v<G, expected>,
+                  "G (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename G::value_type, T>,
+                  "The value type must be the same after calling the F");
+
+    if (has_value())
+      return G(std::in_place, this->m_val);
+    else
+      return std::invoke(std::forward<F>(f), error());
+  }
+  template <class F, class UT = T,
+            std::enable_if_t<std::is_constructible_v<UT, UT&&>>* = nullptr>
+  constexpr auto or_else(F&& f) && {
+    using G = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(error()))>>;
+    static_assert(expected_detail::is_specialization_v<G, expected>,
+                  "G (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename G::value_type, T>,
+                  "The value type must be the same after calling the F");
+
+    if (has_value())
+      return G(std::in_place, std::move(this->m_val));
+    else
+      return std::invoke(std::forward<F>(f), std::move(error()));
+  }
+  template <class F, class UT = T,
+            std::enable_if_t<std::is_constructible_v<UT, const UT>>* = nullptr>
+  constexpr auto or_else(F&& f) const&& {
+    using G = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(error()))>>;
+    static_assert(expected_detail::is_specialization_v<G, expected>,
+                  "G (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename G::value_type, T>,
+                  "The value type must be the same after calling the F");
+
+    if (has_value())
+      return G(std::in_place, std::move(this->m_val));
+    else
+      return std::invoke(std::forward<F>(f), std::move(error()));
+  }
+
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, GE&>>* = nullptr>
+  constexpr auto transform(F&& f) & {
+    using U =
+        expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype((this->m_val))>>;
+    static_assert(expected_detail::is_value_type_valid_v<U>,
+                  "U must be a valid type for expected<U, E>");
+    // FIXME another constraint needed here
+    if (!has_value()) {
+      return expected<U, E>(unexpect, error());
+    } else {
+      if constexpr (std::is_void_v<U>) {
+        std::invoke(std::forward<F>(f), this->m_val);
+        return expected<U, E>{};
+      } else {
+        return expected<U, E>(expected_detail::construct_with_invoke_result_t{},
+                              std::forward<F>(f), this->m_val);
+      }
+    }
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, const GE&>>* = nullptr>
+  constexpr auto transform(F&& f) const& {
+    using U =
+        expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype((this->m_val))>>;
+    static_assert(expected_detail::is_value_type_valid_v<U>,
+                  "U must be a valid type for expected<U, E>");
+    // FIXME another constraint needed here
+    if (!has_value()) {
+      return expected<U, E>(unexpect, error());
+    } else {
+      if constexpr (std::is_void_v<U>) {
+        std::invoke(std::forward<F>(f), this->m_val);
+        return expected<U, E>{};
+      } else {
+        return expected<U, E>(expected_detail::construct_with_invoke_result_t{},
+                              std::forward<F>(f), this->m_val);
+      }
+    }
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, GE&&>>* = nullptr>
+  constexpr auto transform(F&& f) && {
+    using U = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(this->m_val))>>;
+    static_assert(expected_detail::is_value_type_valid_v<U>,
+                  "U must be a valid type for expected<U, E>");
+    // FIXME another constraint needed here
+    if (!has_value()) {
+      return expected<U, E>(unexpect, std::move(error()));
+    } else {
+      if constexpr (std::is_void_v<U>) {
+        std::invoke(std::forward<F>(f), std::move(this->m_val));
+        return expected<U, E>{};
+      } else {
+        return expected<U, E>(expected_detail::construct_with_invoke_result_t{},
+                              std::forward<F>(f), std::move(this->m_val));
+      }
+    }
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, const GE>>* = nullptr>
+  constexpr auto transform(F&& f) const&& {
+    using U = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(this->m_val))>>;
+    static_assert(expected_detail::is_value_type_valid_v<U>,
+                  "U must be a valid type for expected<U, E>");
+    // FIXME another constraint needed here
+    if (!has_value()) {
+      return expected<U, E>(unexpect, std::move(error()));
+    } else {
+      if constexpr (std::is_void_v<U>) {
+        std::invoke(std::forward<F>(f), std::move(this->m_val));
+        return expected<U, E>{};
+      } else {
+        return expected<U, E>(expected_detail::construct_with_invoke_result_t{},
+                              std::forward<F>(f), std::move(this->m_val));
+      }
+    }
+  }
+
+  template <class F, class UT = T,
+            std::enable_if_t<std::is_constructible_v<UT, UT&>>* = nullptr>
+  constexpr auto transform_error(F&& f) & {
+    using G = expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype(error())>>;
+    static_assert(expected_detail::is_error_type_valid_v<G>,
+                  "G must be a valid type for expected<T, G>");
+    // FIXME another constraint needed here
+    if (has_value()) {
+      return expected<T, G>(std::in_place, this->m_val);
+    } else {
+      return expected<T, G>(expected_detail::construct_with_invoke_result_t{}, unexpect,
+                            std::forward<F>(f), error());
+    }
+  }
+  template <class F, class UT = T,
+            std::enable_if_t<std::is_constructible_v<UT, const UT&>>* = nullptr>
+  constexpr auto transform_error(F&& f) const& {
+    using G = expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype(error())>>;
+    static_assert(expected_detail::is_error_type_valid_v<G>,
+                  "G must be a valid type for expected<T, G>");
+    // FIXME another constraint needed here
+    if (has_value()) {
+      return expected<T, G>(std::in_place, this->m_val);
+    } else {
+      return expected<T, G>(expected_detail::construct_with_invoke_result_t{}, unexpect,
+                            std::forward<F>(f), error());
+    }
+  }
+  template <class F, class UT = T,
+            std::enable_if_t<std::is_constructible_v<UT, UT&&>>* = nullptr>
+  constexpr auto transform_error(F&& f) && {
+    using G = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(error()))>>;
+    static_assert(expected_detail::is_error_type_valid_v<G>,
+                  "G must be a valid type for expected<T, G>");
+    // FIXME another constraint needed here
+    if (has_value()) {
+      return expected<T, G>(std::in_place, std::move(this->m_val));
+    } else {
+      return expected<T, G>(expected_detail::construct_with_invoke_result_t{}, unexpect,
+                            std::forward<F>(f), std::move(error()));
+    }
+  }
+  template <class F, class UT = T,
+            std::enable_if_t<std::is_constructible_v<UT, const UT>>* = nullptr>
+  constexpr auto transform_error(F&& f) const&& {
+    using G = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(error()))>>;
+    static_assert(expected_detail::is_error_type_valid_v<G>,
+                  "G must be a valid type for expected<T, G>");
+    // FIXME another constraint needed here
+    if (has_value()) {
+      return expected<T, G>(std::in_place, std::move(this->m_val));
+    } else {
+      return expected<T, G>(expected_detail::construct_with_invoke_result_t{}, unexpect,
+                            std::forward<F>(f), std::move(error()));
+    }
+  }
+
+  template <class T2, class E2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      !std::is_void_v<T2> &&
+          expected_detail::is_equality_result_convertible_to_bool_v<T, T2> &&
+          expected_detail::is_equality_result_convertible_to_bool_v<E, E2>,
+      bool>
+  operator==(const expected& x, const expected<T2, E2>& y) noexcept(
+      expected_detail::is_nothrow_equality_result_convertible_to_bool_v<T, T2> &&
+      expected_detail::is_nothrow_equality_result_convertible_to_bool_v<E, E2>) {
+    if (x.has_value() != y.has_value()) {
+      return false;
+    } else if (x.has_value()) {
+      return *x == *y;
+    } else {
+      return x.error() == y.error();
+    }
+  }
+#if ICEBERG_EXPECTED_CPLUSPLUS < 202'002L
+  template <class T2, class E2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      !std::is_void_v<T2> &&
+          expected_detail::is_equality_result_convertible_to_bool_v<T, T2> &&
+          expected_detail::is_equality_result_convertible_to_bool_v<E, E2>,
+      bool> operator!=(const expected& x,
+                       const expected<T2, E2>& y) noexcept(noexcept(x == y)) {
+    return !(x == y);
+  }
+#endif
+
+  template <class T2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      !expected_detail::is_specialization_v<T2, iceberg::expected> &&
+          expected_detail::is_equality_result_convertible_to_bool_v<T, T2>,
+      bool>
+  operator==(const expected& x, const T2& v) noexcept(
+      expected_detail::is_nothrow_equality_result_convertible_to_bool_v<T, T2>) {
+    if (x.has_value()) {
+      return *x == v;
+    } else {
+      return false;
+    }
+  }
+#if ICEBERG_EXPECTED_CPLUSPLUS < 202'002L
+  template <class T2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      !expected_detail::is_specialization_v<T2, iceberg::expected> &&
+          expected_detail::is_equality_result_convertible_to_bool_v<T, T2>,
+      bool> operator!=(const expected& x, const T2& v) noexcept(noexcept(x == v)) {
+    return !(x == v);
+  }
+#endif
+
+  template <class E2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      expected_detail::is_equality_result_convertible_to_bool_v<E, E2>, bool>
+  operator==(const expected& x, const unexpected<E2>& e) noexcept(
+      expected_detail::is_nothrow_equality_result_convertible_to_bool_v<E, E2>) {
+    if (x.has_value()) {
+      return false;
+    } else {
+      return x.error() == e.error();
+    }
+  }
+#if ICEBERG_EXPECTED_CPLUSPLUS < 202'002L
+  template <class E2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      expected_detail::is_equality_result_convertible_to_bool_v<E, E2>, bool>
+  operator!=(const expected& x, const unexpected<E2>& e) noexcept(noexcept(x == e)) {
+    return !(x == e);
+  }
+#endif
+};
+
+// standalone swap for non-void value type
+template <class T, class E,
+          std::enable_if_t<!std::is_void_v<T> && std::is_move_constructible_v<T> &&
+                           std::is_swappable_v<T> && std::is_move_constructible_v<E> &&
+                           std::is_swappable_v<E> &&
+                           (std::is_nothrow_move_constructible_v<T> ||
+                            std::is_nothrow_move_constructible_v<E>)>* = nullptr>
+constexpr void swap(expected<T, E>& lhs,
+                    expected<T, E>& rhs) noexcept(noexcept(lhs.swap(rhs))) {
+  lhs.swap(rhs);
+}
+
+template <class E>
+class ICEBERG_EXPORT [[nodiscard]]
+expected<void, E> : private expected_detail::move_assign_base<void, E>,
+                    private expected_detail::default_ctor_base<void, E> {
+  static_assert(expected_detail::is_error_type_valid_v<E>);
+
+  using T = void;
+
+  constexpr E* errptr() noexcept { return std::addressof(this->m_unexpect); }
+  constexpr const E* errptr() const noexcept { return std::addressof(this->m_unexpect); }
+
+  constexpr void val() noexcept {}
+
+  constexpr E& err() noexcept { return this->m_unexpect; }
+
+  constexpr void val() const noexcept {}
+
+  constexpr const E& err() const noexcept { return this->m_unexpect; }
+
+  using impl_base = expected_detail::move_assign_base<T, E>;
+  using ctor_base = expected_detail::default_ctor_base<T, E>;
+
+ public:
+  typedef T value_type;
+  typedef E error_type;
+  typedef unexpected<E> unexpected_type;
+
+  template <class U>
+  using rebind = expected<U, error_type>;
+
+  constexpr expected() = default;
+  constexpr expected(const expected& rhs) = default;
+  constexpr expected(expected&& rhs) = default;
+
+  template <
+      class U, class G,
+      std::enable_if_t<!std::is_same_v<expected<U, G>, expected>>* = nullptr,
+      std::enable_if_t<std::is_convertible_v<const G&, E>>* = nullptr,
+      expected_detail::enable_from_other_void_expected_t<E, U, G, const G&>* = nullptr>
+  constexpr expected(const expected<U, G>& rhs) noexcept(
+      std::is_nothrow_constructible_v<E, const G&>)
+      : impl_base(expected_detail::construct_from_expected, rhs),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  template <
+      class U, class G,
+      std::enable_if_t<!std::is_same_v<expected<U, G>, expected>>* = nullptr,
+      std::enable_if_t<!std::is_convertible_v<const G&, E>>* = nullptr,
+      expected_detail::enable_from_other_void_expected_t<E, U, G, const G&>* = nullptr>
+  constexpr explicit expected(const expected<U, G>& rhs) noexcept(
+      std::is_nothrow_constructible_v<E, const G&>)
+      : impl_base(expected_detail::construct_from_expected, rhs),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  template <class U, class G,
+            std::enable_if_t<!std::is_same_v<expected<U, G>, expected>>* = nullptr,
+            std::enable_if_t<std::is_convertible_v<G, E>>* = nullptr,
+            expected_detail::enable_from_other_void_expected_t<E, U, G, G>* = nullptr>
+  constexpr expected(expected<U, G>&& rhs) noexcept(std::is_nothrow_constructible_v<E, G>)
+      : impl_base(expected_detail::construct_from_expected, std::move(rhs)),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  template <class U, class G,
+            std::enable_if_t<!std::is_same_v<expected<U, G>, expected>>* = nullptr,
+            std::enable_if_t<!std::is_convertible_v<G, E>>* = nullptr,
+            expected_detail::enable_from_other_void_expected_t<E, U, G, G>* = nullptr>
+  constexpr explicit expected(expected<U, G>&& rhs) noexcept(
+      std::is_nothrow_constructible_v<E, G>)
+      : impl_base(expected_detail::construct_from_expected, std::move(rhs)),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+#if defined(__cpp_lib_expected) && __cpp_lib_expected >= 202202L
+  // iceberg: library code built as C++23 still spells some errors std::unexpected.
+  template <class G, std::enable_if_t<std::is_constructible_v<E, const G&>>* = nullptr>
+  constexpr explicit(!std::is_convertible_v<const G&, E>) expected(
+      const std::unexpected<G>& e) noexcept(std::is_nothrow_constructible_v<E, const G&>)
+      : expected(unexpect, e.error()) {}
+
+  template <class G, std::enable_if_t<std::is_constructible_v<E, G>>* = nullptr>
+  constexpr explicit(!std::is_convertible_v<G, E>)
+      expected(std::unexpected<G>&& e) noexcept(std::is_nothrow_constructible_v<E, G>)
+      : expected(unexpect, std::move(e.error())) {}
+#endif
+
+  // constructors for unexpected<G>
+
+  // explicit const unexpected<G> &
+  template <class G, std::enable_if_t<!std::is_convertible_v<const G&, E>>* = nullptr,
+            std::enable_if_t<std::is_constructible_v<E, const G&>>* = nullptr>
+  explicit constexpr expected(const unexpected<G>& e) noexcept(
+      std::is_nothrow_constructible_v<E, const G&>)
+      : impl_base(unexpect, e.error()),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // implicit const unexpected<G> &
+  template <class G, std::enable_if_t<std::is_convertible_v<const G&, E>>* = nullptr,
+            std::enable_if_t<std::is_constructible_v<E, const G&>>* = nullptr>
+  constexpr expected(unexpected<G> const& e) noexcept(
+      std::is_nothrow_constructible_v<E, const G&>)
+      : impl_base(unexpect, e.error()),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // explicit unexpected<G> &&
+  template <class G, std::enable_if_t<!std::is_convertible_v<G, E>>* = nullptr,
+            std::enable_if_t<std::is_constructible_v<E, G>>* = nullptr>
+  explicit constexpr expected(unexpected<G>&& e) noexcept(
+      std::is_nothrow_constructible_v<E, G>)
+      : impl_base(unexpect, std::move(e.error())),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // implicit unexpected<G> &&
+  template <class G, std::enable_if_t<std::is_convertible_v<G, E>>* = nullptr,
+            std::enable_if_t<std::is_constructible_v<E, G>>* = nullptr>
+  constexpr expected(unexpected<G>&& e) noexcept(std::is_nothrow_constructible_v<E, G>)
+      : impl_base(unexpect, std::move(e.error())),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // expected(std::in_place_t)
+  constexpr explicit expected(std::in_place_t) noexcept
+      : impl_base(std::in_place), ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // template<class... Args>
+  //     expected(unexpect_t, Args &&...)
+  template <class... Args,
+            std::enable_if_t<std::is_constructible_v<E, Args...>>* = nullptr>
+  constexpr explicit expected(unexpect_t, Args&&... args) noexcept(
+      std::is_nothrow_constructible_v<E, Args...>)
+      : impl_base(unexpect, std::forward<Args>(args)...),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // template<class U, class... Args>
+  //     expected(unexpect_t, std::initializer_list<U>, Args &&...)
+  template <class U, class... Args,
+            std::enable_if_t<std::is_constructible_v<E, std::initializer_list<U>&,
+                                                     Args...>>* = nullptr>
+  constexpr explicit expected(
+      unexpect_t, std::initializer_list<U> il,
+      Args&&... args) noexcept(std::is_nothrow_constructible_v<E,
+                                                               std::initializer_list<U>&,
+                                                               Args...>)
+      : impl_base(unexpect, il, std::forward<Args>(args)...),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  // helper ctor for transform_error()
+  template <class Fn, class... Args>
+  constexpr explicit expected(
+      expected_detail::construct_with_invoke_result_t tag1, unexpect_t tag2, Fn&& func,
+      Args&&... args) noexcept(noexcept(static_cast<E>(std::invoke(std::forward<Fn>(func),
+                                                                   std::forward<Args>(
+                                                                       args)...))))
+      : impl_base(tag1, tag2, std::forward<Fn>(func), std::forward<Args>(args)...),
+        ctor_base(expected_detail::default_constructor_tag{}) {}
+
+  expected& operator=(const expected& rhs) = default;
+  expected& operator=(expected&& rhs) = default;
+
+  template <class G, class GF = const G&,
+            std::enable_if_t<std::is_constructible_v<E, GF> &&
+                             std::is_assignable_v<E&, GF>>* = nullptr>
+  constexpr expected& operator=(const unexpected<G>& rhs) noexcept(
+      std::is_nothrow_constructible_v<E, GF> && std::is_nothrow_assignable_v<E&, GF>) {
+    if (has_value()) {
+      expected_detail::construct_at(errptr(), std::forward<GF>(rhs.error()));
+      this->m_has_val = false;
+    } else {
+      error() = std::forward<GF>(rhs.error());
+    }
+
+    return *this;
+  }
+
+  template <class G, class GF = G,
+            std::enable_if_t<std::is_constructible_v<E, GF> &&
+                             std::is_assignable_v<E&, GF>>* = nullptr>
+  constexpr expected& operator=(unexpected<G>&& rhs) noexcept(
+      std::is_nothrow_constructible_v<E, GF> && std::is_nothrow_assignable_v<E&, GF>) {
+    if (has_value()) {
+      expected_detail::construct_at(errptr(), std::forward<GF>(rhs.error()));
+      this->m_has_val = false;
+    } else {
+      error() = std::forward<GF>(rhs.error());
+    }
+
+    return *this;
+  }
+
+  constexpr void emplace() {
+    if (!has_value()) {
+      if constexpr (!std::is_trivially_destructible_v<E>) {
+        err().~E();
+      }
+      this->m_has_val = true;
+    }
+  }
+
+  template <class OE = E>
+  constexpr std::enable_if_t<std::is_swappable_v<OE> && std::is_move_constructible_v<OE>>
+  swap(expected& rhs) noexcept(std::is_nothrow_move_constructible_v<E> &&
+                               std::is_nothrow_swappable_v<E>) {
+    using std::swap;
+    if (this->m_has_val && rhs.m_has_val) {
+      // do nothing
+    } else if (this->m_has_val) {
+      expected_detail::construct_at(std::addressof(error()), std::move(rhs.error()));
+      if constexpr (!std::is_trivially_destructible_v<E>) {
+        rhs.error().~E();
+      }
+      this->m_has_val = false;
+      rhs.m_has_val = true;
+    } else if (rhs.m_has_val) {
+      expected_detail::construct_at(std::addressof(rhs.error()), std::move(error()));
+      if constexpr (!std::is_trivially_destructible_v<E>) {
+        error().~E();
+      }
+      this->m_has_val = true;
+      rhs.m_has_val = false;
+    } else {
+      swap(error(), rhs.error());  // ADL
+    }
+  }
+
+  constexpr void operator*() const noexcept { return val(); }
+
+  constexpr bool has_value() const noexcept { return this->m_has_val; }
+  constexpr explicit operator bool() const noexcept { return this->m_has_val; }
+
+  constexpr void value() const& {
+    static_assert(std::is_copy_constructible_v<E>,
+                  "E must be copy constructible, by LWG-3940");
+    if (!has_value()) ICEBERG_EXPECTED_THROW(bad_expected_access(err()));
+  }
+
+  constexpr void value() && {
+    static_assert(std::is_copy_constructible_v<E>,
+                  "E must be copy constructible, by LWG-3940");
+    static_assert(std::is_move_constructible_v<E>,
+                  "E must be move constructible, by LWG-3940");
+    if (!has_value()) ICEBERG_EXPECTED_THROW(bad_expected_access(std::move(err())));
+  }
+
+  constexpr const E& error() const& noexcept { return err(); }
+  constexpr E& error() & noexcept { return err(); }
+  constexpr const E&& error() const&& noexcept { return std::move(err()); }
+  constexpr E&& error() && noexcept { return std::move(err()); }
+
+  template <class G = E>
+  constexpr E error_or(G&& v) const& noexcept(
+      std::is_nothrow_copy_constructible_v<E> &&
+      expected_detail::is_nothrow_convertible_v<G, E>) {
+    static_assert(std::is_copy_constructible_v<E>, "E must be copy-constructible");
+    static_assert(std::is_convertible_v<G, E>, "is_convertible_v<G, E> must be true");
+    if (this->m_has_val) {
+      return static_cast<E>(std::forward<G>(v));
+    } else {
+      return this->m_unexpect;
+    }
+  }
+  template <class G = E>
+  constexpr E error_or(G&& v) && noexcept(
+      std::is_nothrow_move_constructible_v<E> &&
+      expected_detail::is_nothrow_convertible_v<G, E>) {
+    static_assert(std::is_move_constructible_v<E>, "E must be move-constructible");
+    static_assert(std::is_convertible_v<G, E>, "is_convertible_v<G, E> must be true");
+    if (this->m_has_val) {
+      return static_cast<E>(std::forward<G>(v));
+    } else {
+      return std::move(this->m_unexpect);
+    }
+  }
+
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, GE&>>* = nullptr>
+  constexpr auto and_then(F&& f) & {
+    using U = expected_detail::remove_cvref_t<std::invoke_result_t<F>>;
+    static_assert(expected_detail::is_specialization_v<U, iceberg::expected>,
+                  "U (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename U::error_type, E>,
+                  "The error type must be the same after calling the F");
+
+    if (has_value())
+      return std::invoke(std::forward<F>(f));
+    else
+      return U(unexpect, error());
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, const GE&>>* = nullptr>
+  constexpr auto and_then(F&& f) const& {
+    using U = expected_detail::remove_cvref_t<std::invoke_result_t<F>>;
+    static_assert(expected_detail::is_specialization_v<U, iceberg::expected>,
+                  "U (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename U::error_type, E>,
+                  "The error type must be the same after calling the F");
+
+    if (has_value())
+      return std::invoke(std::forward<F>(f));
+    else
+      return U(unexpect, error());
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, GE&&>>* = nullptr>
+  constexpr auto and_then(F&& f) && {
+    using U = expected_detail::remove_cvref_t<std::invoke_result_t<F>>;
+    static_assert(expected_detail::is_specialization_v<U, iceberg::expected>,
+                  "U (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename U::error_type, E>,
+                  "The error type must be the same after calling the F");
+
+    if (has_value())
+      return std::invoke(std::forward<F>(f));
+    else
+      return U(unexpect, std::move(error()));
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, const GE>>* = nullptr>
+  constexpr auto and_then(F&& f) const&& {
+    using U = expected_detail::remove_cvref_t<std::invoke_result_t<F>>;
+    static_assert(expected_detail::is_specialization_v<U, iceberg::expected>,
+                  "U (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename U::error_type, E>,
+                  "The error type must be the same after calling the F");
+
+    if (has_value())
+      return std::invoke(std::forward<F>(f));
+    else
+      return U(unexpect, std::move(error()));
+  }
+
+  template <class F>
+  constexpr auto or_else(F&& f) & {
+    using G = expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype(error())>>;
+    static_assert(expected_detail::is_specialization_v<G, iceberg::expected>,
+                  "G (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename G::value_type, T>,
+                  "The value type must be the same after calling the F");
+
+    if (has_value())
+      return G();
+    else
+      return std::invoke(std::forward<F>(f), error());
+  }
+  template <class F>
+  constexpr auto or_else(F&& f) const& {
+    using G = expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype(error())>>;
+    static_assert(expected_detail::is_specialization_v<G, iceberg::expected>,
+                  "G (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename G::value_type, T>,
+                  "The value type must be the same after calling the F");
+
+    if (has_value())
+      return G();
+    else
+      return std::invoke(std::forward<F>(f), error());
+  }
+  template <class F>
+  constexpr auto or_else(F&& f) && {
+    using G = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(error()))>>;
+    static_assert(expected_detail::is_specialization_v<G, iceberg::expected>,
+                  "G (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename G::value_type, T>,
+                  "The value type must be the same after calling the F");
+
+    if (has_value())
+      return G();
+    else
+      return std::invoke(std::forward<F>(f), std::move(error()));
+  }
+  template <class F>
+  constexpr auto or_else(F&& f) const&& {
+    using G = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(error()))>>;
+    static_assert(expected_detail::is_specialization_v<G, iceberg::expected>,
+                  "G (return type of F) must be specialization of expected");
+    static_assert(std::is_same_v<typename G::value_type, T>,
+                  "The value type must be the same after calling the F");
+
+    if (has_value())
+      return G();
+    else
+      return std::invoke(std::forward<F>(f), std::move(error()));
+  }
+
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, GE&>>* = nullptr>
+  constexpr auto transform(F&& f) & {
+    using U = expected_detail::remove_cvref_t<std::invoke_result_t<F>>;
+    static_assert(expected_detail::is_value_type_valid_v<U>,
+                  "U must be a valid type for expected<U, E>");
+    // FIXME another constraint needed here
+    if (!has_value()) {
+      return expected<U, E>(unexpect, error());
+    } else {
+      if constexpr (std::is_void_v<U>) {
+        std::invoke(std::forward<F>(f));
+        return expected<U, E>{};
+      } else {
+        return expected<U, E>(expected_detail::construct_with_invoke_result_t{},
+                              std::forward<F>(f));
+      }
+    }
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, const GE&>>* = nullptr>
+  constexpr auto transform(F&& f) const& {
+    using U = expected_detail::remove_cvref_t<std::invoke_result_t<F>>;
+    static_assert(expected_detail::is_value_type_valid_v<U>,
+                  "U must be a valid type for expected<U, E>");
+    // FIXME another constraint needed here
+    if (!has_value()) {
+      return expected<U, E>(unexpect, error());
+    } else {
+      if constexpr (std::is_void_v<U>) {
+        std::invoke(std::forward<F>(f));
+        return expected<U, E>{};
+      } else {
+        return expected<U, E>(expected_detail::construct_with_invoke_result_t{},
+                              std::forward<F>(f));
+      }
+    }
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, GE&&>>* = nullptr>
+  constexpr auto transform(F&& f) && {
+    using U = expected_detail::remove_cvref_t<std::invoke_result_t<F>>;
+    static_assert(expected_detail::is_value_type_valid_v<U>,
+                  "U must be a valid type for expected<U, E>");
+    // FIXME another constraint needed here
+    if (!has_value()) {
+      return expected<U, E>(unexpect, std::move(error()));
+    } else {
+      if constexpr (std::is_void_v<U>) {
+        std::invoke(std::forward<F>(f));
+        return expected<U, E>{};
+      } else {
+        return expected<U, E>(expected_detail::construct_with_invoke_result_t{},
+                              std::forward<F>(f));
+      }
+    }
+  }
+  template <class F, class GE = E,
+            std::enable_if_t<std::is_constructible_v<GE, const GE>>* = nullptr>
+  constexpr auto transform(F&& f) const&& {
+    using U = expected_detail::remove_cvref_t<std::invoke_result_t<F>>;
+    static_assert(expected_detail::is_value_type_valid_v<U>,
+                  "U must be a valid type for expected<U, E>");
+    // FIXME another constraint needed here
+    if (!has_value()) {
+      return expected<U, E>(unexpect, std::move(error()));
+    } else {
+      if constexpr (std::is_void_v<U>) {
+        std::invoke(std::forward<F>(f));
+        return expected<U, E>{};
+      } else {
+        return expected<U, E>(expected_detail::construct_with_invoke_result_t{},
+                              std::forward<F>(f));
+      }
+    }
+  }
+
+  template <class F>
+  constexpr auto transform_error(F&& f) & {
+    using G = expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype(error())>>;
+    static_assert(expected_detail::is_error_type_valid_v<G>,
+                  "G must be a valid type for expected<void, G>");
+    // FIXME another constraint needed here
+    if (has_value()) {
+      return expected<T, G>();
+    } else {
+      return expected<T, G>(expected_detail::construct_with_invoke_result_t{}, unexpect,
+                            std::forward<F>(f), error());
+    }
+  }
+  template <class F>
+  constexpr auto transform_error(F&& f) const& {
+    using G = expected_detail::remove_cvref_t<std::invoke_result_t<F, decltype(error())>>;
+    static_assert(expected_detail::is_error_type_valid_v<G>,
+                  "G must be a valid type for expected<void, G>");
+    // FIXME another constraint needed here
+    if (has_value()) {
+      return expected<T, G>();
+    } else {
+      return expected<T, G>(expected_detail::construct_with_invoke_result_t{}, unexpect,
+                            std::forward<F>(f), error());
+    }
+  }
+  template <class F>
+  constexpr auto transform_error(F&& f) && {
+    using G = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(error()))>>;
+    static_assert(expected_detail::is_error_type_valid_v<G>,
+                  "G must be a valid type for expected<void, G>");
+    // FIXME another constraint needed here
+    if (has_value()) {
+      return expected<T, G>();
+    } else {
+      return expected<T, G>(expected_detail::construct_with_invoke_result_t{}, unexpect,
+                            std::forward<F>(f), std::move(error()));
+    }
+  }
+  template <class F>
+  constexpr auto transform_error(F&& f) const&& {
+    using G = expected_detail::remove_cvref_t<
+        std::invoke_result_t<F, decltype(std::move(error()))>>;
+    static_assert(expected_detail::is_error_type_valid_v<G>,
+                  "G must be a valid type for expected<void, G>");
+    // FIXME another constraint needed here
+    if (has_value()) {
+      return expected<T, G>();
+    } else {
+      return expected<T, G>(expected_detail::construct_with_invoke_result_t{}, unexpect,
+                            std::forward<F>(f), std::move(error()));
+    }
+  }
+
+  template <class T2, class E2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      std::is_void_v<T2> &&
+          expected_detail::is_equality_result_convertible_to_bool_v<E, E2>,
+      bool>
+  operator==(const expected& x, const expected<T2, E2>& y) noexcept(
+      expected_detail::is_nothrow_equality_result_convertible_to_bool_v<E, E2>) {
+    if (x.has_value() != y.has_value()) {
+      return false;
+    } else if (x.has_value()) {
+      return true;
+    } else {
+      return x.error() == y.error();
+    }
+  }
+#if ICEBERG_EXPECTED_CPLUSPLUS < 202'002L
+  template <class T2, class E2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      std::is_void_v<T2> &&
+          expected_detail::is_equality_result_convertible_to_bool_v<E, E2>,
+      bool> operator!=(const expected& x,
+                       const expected<T2, E2>& y) noexcept(noexcept(x == y)) {
+    return !(x == y);
+  }
+#endif
+
+  template <class E2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      expected_detail::is_equality_result_convertible_to_bool_v<E, E2>, bool>
+  operator==(const expected& x, const unexpected<E2>& e) noexcept(
+      expected_detail::is_nothrow_equality_result_convertible_to_bool_v<E, E2>) {
+    if (x.has_value()) {
+      return false;
+    } else {
+      return x.error() == e.error();
+    }
+  }
+#if ICEBERG_EXPECTED_CPLUSPLUS < 202'002L
+  template <class E2>
+  [[nodiscard]] friend constexpr std::enable_if_t<
+      expected_detail::is_equality_result_convertible_to_bool_v<E, E2>, bool>
+  operator!=(const expected& x, const unexpected<E2>& e) noexcept(noexcept(x == e)) {
+    return !(x == e);
+  }
+#endif
+};
+
+#if ICEBERG_EXPECTED_CPLUSPLUS < 202'002L
+// Deduce the expected operand to reject conversions exposed by MSVC's permissive C++17
+// hidden-friend lookup.
+template <class T, class E, class T2>
+[[nodiscard]] constexpr std::enable_if_t<
+    !std::is_void_v<T> && !expected_detail::is_specialization_v<T2, iceberg::expected> &&
+        expected_detail::is_equality_result_convertible_to_bool_v<T, T2>,
+    bool>
+operator==(const T2& v, const expected<T, E>& x) noexcept(noexcept(x == v)) {
+  return x == v;
+}
+
+template <class T, class E, class T2>
+[[nodiscard]] constexpr std::enable_if_t<
+    !std::is_void_v<T> && !expected_detail::is_specialization_v<T2, iceberg::expected> &&
+        expected_detail::is_equality_result_convertible_to_bool_v<T, T2>,
+    bool>
+operator!=(const T2& v, const expected<T, E>& x) noexcept(noexcept(x == v)) {
+  return x != v;
+}
+
+template <
+    class T, class E, class E2,
+    std::enable_if_t<expected_detail::is_equality_result_convertible_to_bool_v<E, E2>>* =
+        nullptr>
+[[nodiscard]] constexpr bool operator==(const unexpected<E2>& e,
+                                        const expected<T, E>& x) noexcept(noexcept(x ==
+                                                                                   e)) {
+  return x == e;
+}
+
+template <
+    class T, class E, class E2,
+    std::enable_if_t<expected_detail::is_equality_result_convertible_to_bool_v<E, E2>>* =
+        nullptr>
+[[nodiscard]] constexpr bool operator!=(const unexpected<E2>& e,
+                                        const expected<T, E>& x) noexcept(noexcept(x ==
+                                                                                   e)) {
+  return x != e;
+}
+#endif
+
+// standalone swap for void value type
+template <class E, std::enable_if_t<std::is_move_constructible_v<E> &&
+                                    std::is_swappable_v<E>>* = nullptr>
+constexpr void swap(expected<void, E>& lhs,
+                    expected<void, E>& rhs) noexcept(noexcept(lhs.swap(rhs))) {
+  lhs.swap(rhs);
+}
+
+}  // namespace iceberg
+
+// NOLINTEND
diff --git a/src/iceberg/test/CMakeLists.txt b/src/iceberg/test/CMakeLists.txt
index 6f6ff7603..a8e036164 100644
--- a/src/iceberg/test/CMakeLists.txt
+++ b/src/iceberg/test/CMakeLists.txt
@@ -133,6 +133,7 @@ add_iceberg_test(util_test
                  data_file_set_test.cc
                  decimal_test.cc
                  endian_test.cc
+                 expected_test.cc
                  file_io_test.cc
                  formatter_test.cc
                  stream_test.cc
diff --git a/src/iceberg/test/expected_test.cc b/src/iceberg/test/expected_test.cc
new file mode 100644
index 000000000..d053b104e
--- /dev/null
+++ b/src/iceberg/test/expected_test.cc
@@ -0,0 +1,636 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "iceberg/expected.h"
+
+#include <gtest/gtest.h>
+
+TEST(ExpectedTest, DefaultCons) {
+  iceberg::expected<int, int> e1;
+  iceberg::expected<int, int> e2{};
+  EXPECT_EQ(e1.value(), 0);
+  EXPECT_EQ(e2.value(), 0);
+}
+
+TEST(ExpectedTest, InplaceCons) {
+  iceberg::expected<void, int> e1{iceberg::unexpect};
+  iceberg::expected<void, int> e2{iceberg::unexpect, 42};
+  iceberg::expected<int, int> e3{iceberg::unexpect};
+  iceberg::expected<int, int> e4{iceberg::unexpect, 42};
+
+  EXPECT_EQ(e1.error(), 0);
+  EXPECT_EQ(e2.error(), 42);
+  EXPECT_EQ(e3.error(), 0);
+  EXPECT_EQ(e4.error(), 42);
+}
+
+TEST(ExpectedTest, ImplicitConversion) {
+  iceberg::expected<int, int> e = 42;
+
+  EXPECT_EQ(e.value(), 42);
+}
+
+TEST(ExpectedTest, ExplicitConversion) {
+  iceberg::expected<std::string, int> e1 = iceberg::unexpected<int>(42);
+  iceberg::expected<std::string, int> e2{iceberg::unexpect, 42};
+  EXPECT_EQ(e1.error(), 42);
+  EXPECT_EQ(e2.error(), 42);
+}
+
+TEST(ExpectedTest, ImplicitConversionFrom) {
+  EXPECT_FALSE((std::is_convertible_v<iceberg::expected<std::string, int>, int>));
+}
+
+TEST(ExpectedTest, ExplictVoidE) {
+  iceberg::expected<void, int> e1 = {};
+  iceberg::expected<void, int> e2 = iceberg::unexpected{42};
+
+  EXPECT_TRUE(e1.has_value());
+  EXPECT_TRUE((std::is_same_v<decltype(e1.value()), void>));
+  EXPECT_EQ(e1.error(), 0);
+  EXPECT_EQ(e2.error(), 42);
+}
+
+TEST(ExpectedTest, Emplace) {
+  struct S {
+    S(int i, double d) noexcept : i(i), d(d) {}
+    int i;
+    double d;
+  };
+  iceberg::expected<S, std::nullopt_t> e{iceberg::unexpect, std::nullopt};
+  e.emplace(42, 3.14);
+  EXPECT_EQ(e.value().i, 42);
+  EXPECT_EQ(e.value().d, 3.14);
+}
+
+TEST(ExpectedTest, Equality) {
+  iceberg::expected<int, int> const v1;
+  iceberg::expected<int, int> const v2{42};
+  iceberg::expected<int, int> const v3 = 42;
+  iceberg::expected<int, int> const e1{iceberg::unexpect, 0};
+  iceberg::expected<int, int> const e2{iceberg::unexpect, 42};
+  iceberg::expected<int, int> const e3 = iceberg::unexpected(42);
+  EXPECT_TRUE(v1 != v2);
+  EXPECT_TRUE(v2 == v3);
+  EXPECT_TRUE(v1 != e1);
+  EXPECT_TRUE(v1 != e2);
+  EXPECT_TRUE(e1 != e2);
+  EXPECT_TRUE(e2 == e3);
+  EXPECT_TRUE(e1 != v1);
+  EXPECT_TRUE(e1 != v2);
+}
+
+TEST(ExpectedTest, UnexpectedError) {
+  auto e = iceberg::unexpected(42);
+  EXPECT_EQ(e.error(), 42);
+}
+
+TEST(ExpectedTest, UnexpectedEquality) {
+  const iceberg::unexpected<std::string> error1("error1");
+  const iceberg::unexpected<std::string> error1_copy("error1");
+  const iceberg::unexpected<std::string> error2("error2");
+
+  EXPECT_EQ(error1, error1_copy);
+  EXPECT_NE(error1, error2);
+}
+
+TEST(ExpectedTest, BadExpectedAccess) {
+  iceberg::expected<void, int> e = iceberg::unexpected(42);
+  EXPECT_THROW(
+      {
+        try {
+          e.value();
+        } catch (const iceberg::bad_expected_access<int>& ex) {
+          // and this tests that it has the correct message
+          EXPECT_EQ(ex.error(), 42);
+          throw;
+        }
+      },
+      iceberg::bad_expected_access<int>);
+}
+
+TEST(ExpectedTest, ExpectedVoidEEmplace) {
+  iceberg::expected<void, int> e1{std::in_place};
+  iceberg::expected<void, int> e2;
+  e2.emplace();
+}
+
+TEST(ExpectedTest, Swap) {
+  iceberg::expected<int, int> e1{42};
+  iceberg::expected<int, int> e2{1'337};
+
+  e1.swap(e2);
+  EXPECT_EQ(e1.value(), 1'337);
+  EXPECT_EQ(e2.value(), 42);
+
+  swap(e1, e2);
+  EXPECT_EQ(e1.value(), 42);
+  EXPECT_EQ(e2.value(), 1'337);
+}
+
+TEST(ExpectedTest, CopyInitialization) {
+  {
+    iceberg::expected<std::string, int> e = {};
+    EXPECT_TRUE(e);
+  }
+}
+
+TEST(ExpectedTest, BraceContructedValue) {
+  {  // non-void
+    iceberg::expected<int, int> e{{}};
+    EXPECT_TRUE(e);
+  }
+#if !defined(__GNUC__)
+  {  // std::string
+    iceberg::expected<std::string, int> e{{}};
+    EXPECT_TRUE(e);
+  }
+#endif
+}
+
+TEST(ExpectedTest, LWG3836) {
+  struct BaseError {};
+  struct DerivedError : BaseError {};
+
+  iceberg::expected<bool, DerivedError> e1(false);
+  iceberg::expected<bool, BaseError> e2(e1);
+  EXPECT_TRUE(!e2.value());
+
+  iceberg::expected<void, DerivedError> e3{};
+  iceberg::expected<void, BaseError> e4(e3);
+  EXPECT_TRUE(e4.has_value());
+}
+
+TEST(ExpectedTest, Assignment) {
+  // non-void
+  {
+    iceberg::expected<int, int> e1{iceberg::unexpect, 1'337};
+    iceberg::expected<int, int> e2{42};
+
+    e1 = e2;
+    EXPECT_TRUE(e1);
+  }
+
+  // void
+  {
+    iceberg::expected<void, int> e1{iceberg::unexpect, 1'337};
+    iceberg::expected<void, int> e2{};
+
+    e1 = e2;
+    EXPECT_TRUE(e1);
+  }
+}
+
+TEST(ExpectedTest, Move) {
+  {
+    struct user_provided_move {
+      user_provided_move() = default;
+      user_provided_move(user_provided_move&&) noexcept {}
+    };
+
+    struct defaulted_move {
+      defaulted_move() = default;
+      defaulted_move(defaulted_move&&) = default;
+    };
+
+    {
+      using Expected = iceberg::expected<user_provided_move, int>;
+      Expected t1;
+      Expected tm1(std::move(t1));
+      EXPECT_TRUE(tm1);
+    }
+    {
+      using Expected = iceberg::expected<defaulted_move, int>;
+      Expected t2;
+      Expected tm2(std::move(t2));  // should compile
+      EXPECT_TRUE(tm2);
+    }
+  }
+
+  {
+    class MoveOnly {
+     public:
+      MoveOnly() = default;
+
+      // Non-copyable
+      MoveOnly(const MoveOnly&) = delete;
+      MoveOnly& operator=(const MoveOnly&) = delete;
+
+      // Movable trivially
+      MoveOnly(MoveOnly&&) = default;
+      MoveOnly& operator=(MoveOnly&&) = default;
+    };
+
+    {
+      using Expected = iceberg::expected<MoveOnly, int>;
+      Expected a{};
+      Expected b = std::move(a);  // should compile
+    }
+  }
+}
+
+namespace {
+
+template <bool ShouldEqual, typename T, typename U>
+constexpr bool EqualityTester(T const& lhs, U const& rhs) {
+  return (lhs == rhs) == ShouldEqual && (lhs != rhs) != ShouldEqual &&
+         (rhs == lhs) == ShouldEqual && (rhs != lhs) != ShouldEqual;
+}
+
+struct Type1 {
+  std::string value;
+
+  explicit Type1(std::string v) : value(std::move(v)) {}
+  explicit Type1(const char* v) : value(v) {}
+  Type1(Type1 const&) = delete;
+  Type1& operator=(Type1 const&) = delete;
+  Type1(Type1&& other) = default;
+  Type1& operator=(Type1&&) = default;
+  ~Type1() = default;
+
+  bool operator==(Type1 const& rhs) const { return value == rhs.value; }
+};
+
+struct Type2 {
+  std::string value;
+
+  explicit Type2(std::string v) : value(std::move(v)) {}
+  explicit Type2(const char* v) : value(v) {}
+  Type2(Type2 const&) = delete;
+  Type2& operator=(Type2 const&) = delete;
+  Type2(Type2&& other) = default;
+  Type2& operator=(Type2&&) = default;
+  ~Type2() = default;
+
+  bool operator==(Type2 const& rhs) const { return value == rhs.value; }
+};
+
+inline bool operator==(Type1 const& lhs, Type2 const& rhs) {
+  return lhs.value == rhs.value;
+}
+
+inline bool operator==(Type2 const& lhs, Type1 const& rhs) { return rhs == lhs; }
+
+}  // namespace
+
+TEST(ExpectedTest, EqualityTest) {
+  // expected<T, E> (T is not void)
+  {
+    using T = Type1;
+    using E = Type2;
+    using Expected = iceberg::expected<T, E>;
+
+    // compare with same type expected<T, E>
+    {
+      Expected const value1("value1");
+      Expected const value2("value2");
+      Expected const value1Copy("value1");
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      Expected const error2 = iceberg::unexpected<E>("error2");
+      Expected const error1Copy = iceberg::unexpected<E>("error1");
+
+      EXPECT_TRUE(EqualityTester<true>(value1, value1Copy));
+      EXPECT_TRUE(EqualityTester<false>(value1, value2));
+      EXPECT_TRUE(EqualityTester<true>(error1, error1Copy));
+      EXPECT_TRUE(EqualityTester<false>(error1, error2));
+      EXPECT_TRUE(EqualityTester<false>(value1, error1));
+    }
+
+    // compare with different type expected<T2, E2>
+    {
+      using T2 = Type2;
+      using E2 = Type1;
+      ASSERT_FALSE((std::is_same_v<T, T2>));
+      ASSERT_FALSE((std::is_same_v<E, E2>));
+      using Expected2 = iceberg::expected<T2, E2>;
+
+      Expected const value1("value1");
+      Expected2 const value2("value2");
+      Expected2 const value1Same("value1");
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      Expected2 const error2 = iceberg::unexpected<E2>("error2");
+      Expected2 const error1Same = iceberg::unexpected<E2>("error1");
+
+      EXPECT_TRUE(EqualityTester<true>(value1, value1Same));
+      EXPECT_TRUE(EqualityTester<false>(value1, value2));
+      EXPECT_TRUE(EqualityTester<true>(error1, error1Same));
+      EXPECT_TRUE(EqualityTester<false>(error1, error2));
+      EXPECT_TRUE(EqualityTester<false>(value1, error1));
+    }
+
+    // compare with same value type T
+    {
+      Expected const value1("value1");
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      T const value2("value2");
+      T const value1Same("value1");
+
+      EXPECT_TRUE(EqualityTester<true>(value1, value1Same));
+      EXPECT_TRUE(EqualityTester<false>(value1, value2));
+      EXPECT_TRUE(EqualityTester<false>(error1, value2));
+    }
+
+    // compare with different value type T2
+    {
+      using T2 = Type2;
+      ASSERT_FALSE((std::is_same_v<T, T2>));
+
+      Expected const value1("value1");
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      T2 const value2("value2");
+      T2 const value1Same("value1");
+
+      EXPECT_TRUE(EqualityTester<true>(value1, value1Same));
+      EXPECT_TRUE(EqualityTester<false>(value1, value2));
+      EXPECT_TRUE(EqualityTester<false>(error1, value2));
+    }
+
+    // compare with same error type unexpected<E>
+    {
+      Expected const value1("value1");
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      auto const error2 = iceberg::unexpected<E>("error2");
+      auto const error1Same = iceberg::unexpected<E>("error1");
+
+      EXPECT_TRUE(EqualityTester<true>(error1, error1Same));
+      EXPECT_TRUE(EqualityTester<false>(error1, error2));
+      EXPECT_TRUE(EqualityTester<false>(value1, error2));
+    }
+
+    // compare with different error type unexpected<E2>
+    {
+      using E2 = Type1;
+      ASSERT_FALSE((std::is_same_v<E, E2>));
+
+      Expected const value1("value1");
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      auto const error2 = iceberg::unexpected<E2>("error2");
+      auto const error1Same = iceberg::unexpected<E2>("error1");
+
+      EXPECT_TRUE(EqualityTester<true>(error1, error1Same));
+      EXPECT_TRUE(EqualityTester<false>(error1, error2));
+      EXPECT_TRUE(EqualityTester<false>(value1, error2));
+    }
+  }
+
+  // expected<void, E>
+  {
+    using E = Type1;
+    using Expected = iceberg::expected<void, E>;
+
+    // compare with same type expected<void, E>
+    {
+      Expected const value1;
+      Expected const value2;
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      Expected const error2 = iceberg::unexpected<E>("error2");
+      Expected const error1Copy = iceberg::unexpected<E>("error1");
+
+      EXPECT_TRUE(EqualityTester<true>(value1, value2));
+      EXPECT_TRUE(EqualityTester<true>(error1, error1Copy));
+      EXPECT_TRUE(EqualityTester<false>(error1, error2));
+      EXPECT_TRUE(EqualityTester<false>(value1, error1));
+    }
+
+    // compare with different type expected<void, E2>
+    {
+      using E2 = Type2;
+      ASSERT_FALSE((std::is_same_v<E, E2>));
+      using Expected2 = iceberg::expected<void, E2>;
+
+      Expected const value1;
+      Expected2 const value2;
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      Expected2 const error2 = iceberg::unexpected<E2>("error2");
+      Expected2 const error1Same = iceberg::unexpected<E2>("error1");
+
+      EXPECT_TRUE(EqualityTester<true>(value1, value2));
+      EXPECT_TRUE(EqualityTester<true>(error1, error1Same));
+      EXPECT_TRUE(EqualityTester<false>(error1, error2));
+      EXPECT_TRUE(EqualityTester<false>(value1, error1));
+    }
+
+    // compare with same error type unexpected<E>
+    {
+      Expected const value1;
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      auto const error2 = iceberg::unexpected<E>("error2");
+      auto const error1Same = iceberg::unexpected<E>("error1");
+
+      EXPECT_TRUE(EqualityTester<true>(error1, error1Same));
+      EXPECT_TRUE(EqualityTester<false>(error1, error2));
+      EXPECT_TRUE(EqualityTester<false>(value1, error2));
+    }
+
+    // compare with different error type unexpected<E2>
+    {
+      using E2 = Type2;
+      ASSERT_FALSE((std::is_same_v<E, E2>));
+
+      Expected const value1;
+      Expected const error1 = iceberg::unexpected<E>("error1");
+      auto const error2 = iceberg::unexpected<E2>("error2");
+      auto const error1Same = iceberg::unexpected<E2>("error1");
+
+      EXPECT_TRUE(EqualityTester<true>(error1, error1Same));
+      EXPECT_TRUE(EqualityTester<false>(error1, error2));
+      EXPECT_TRUE(EqualityTester<false>(value1, error2));
+    }
+  }
+}
+
+TEST(ExpectedTest, AndThen) {
+  using T = std::string;
+  using Expected = iceberg::expected<int, T>;
+
+  {  // non-void
+    using Expected2 = iceberg::expected<double, T>;
+
+    Expected e = 42;
+
+    auto const newVal = e.and_then([](int x) { return Expected2{x * 2}; });
+
+    EXPECT_TRUE((std::is_same_v<std::remove_cv_t<decltype(newVal)>, Expected2>));
+  }
+  {  // void
+    using Expected2 = iceberg::expected<void, T>;
+
+    Expected e = 42;
+
+    auto const newVal = e.and_then([](int) -> Expected2 { return Expected2{}; });
+
+    EXPECT_TRUE((std::is_same_v<std::remove_cv_t<decltype(newVal)>, Expected2>));
+  }
+}
+
+TEST(ExpectedTest, VoidAndThen) {
+  using T = std::string;
+  using Expected = iceberg::expected<void, T>;
+
+  {  // non-void
+    using Expected2 = iceberg::expected<double, T>;
+
+    Expected e{};
+
+    auto const newVal = e.and_then([]() { return Expected2{}; });
+
+    EXPECT_TRUE((std::is_same_v<std::remove_cv_t<decltype(newVal)>, Expected2>));
+  }
+  {  // void
+    using Expected2 = iceberg::expected<void, T>;
+
+    Expected e{};
+
+    auto const newVal = e.and_then([]() -> Expected2 { return Expected2{}; });
+
+    EXPECT_TRUE((std::is_same_v<std::remove_cv_t<decltype(newVal)>, Expected2>));
+  }
+}
+
+TEST(ExpectedTest, OrElse) {
+  using T = std::string;
+  using Expected = iceberg::expected<T, int>;
+
+  {  // non-void
+    using Expected2 = iceberg::expected<T, double>;
+
+    Expected e{};
+
+    auto const newVal = e.or_else([](auto&&) { return Expected2{}; });
+
+    EXPECT_TRUE((std::is_same_v<std::remove_cv_t<decltype(newVal)>, Expected2>));
+  }
+}
+
+TEST(ExpectedTest, VoidOrElse) {
+  using Expected = iceberg::expected<void, int>;
+
+  {  // void
+    using Expected2 = iceberg::expected<void, double>;
+
+    Expected e{};
+
+    auto const newVal = e.or_else([](auto&&) { return Expected2{}; });
+
+    EXPECT_TRUE(newVal.has_value());
+    EXPECT_TRUE((std::is_same_v<std::remove_cv_t<decltype(newVal)>, Expected2>));
+  }
+}
+
+TEST(ExpectedTest, Transform) {
+  using Expected = iceberg::expected<int, int>;
+
+  {
+    Expected e{42};
+
+    auto const newVal = e.transform([](int n) { return n + 100; });
+
+    EXPECT_TRUE((std::is_same_v<std::remove_cv_t<decltype(newVal)>, Expected>));
+    EXPECT_EQ(newVal.value(), 142);
+  }
+
+  {
+    Expected e = iceberg::unexpected{-1};
+    auto const newVal = e.transform_error([](int n) { return n + 100; });
+
+    EXPECT_EQ(newVal.error(), 99);
+  }
+}
+
+namespace {
+struct FromType {};
+
+enum class NoThrowConvertible {
+  Yes,
+  No,
+};
+
+template <NoThrowConvertible N>
+struct ToType;
+
+template <>
+struct ToType<NoThrowConvertible::Yes> {
+  ToType() = default;
+  ToType(ToType const&) = default;
+  ToType(ToType&&) = default;
+
+  explicit ToType(FromType const&) noexcept {}
+};
+
+template <>
+struct ToType<NoThrowConvertible::No> {
+  ToType() = default;
+  ToType(ToType const&) = default;
+  ToType(ToType&&) = default;
+
+  explicit ToType(FromType const&) noexcept(false) {}
+};
+
+}  // namespace
+
+TEST(ExpectedTest, ValueOrNoexcept) {
+  {  // noexcept(true)
+    using T = ToType<NoThrowConvertible::Yes>;
+    using E = int;
+    using Expected = iceberg::expected<T, E>;
+    Expected e;
+    EXPECT_TRUE(noexcept(e.value_or(FromType{})));
+  }
+  {  // noexcept(false)
+    using T = ToType<NoThrowConvertible::No>;
+    using E = int;
+    using Expected = iceberg::expected<T, E>;
+    Expected e;
+    EXPECT_FALSE(noexcept(e.value_or(FromType{})));
+  }
+}
+
+TEST(ExpectedTest, ErrorOrNoexcept) {
+  {  // noexcept(true)
+    using T = int;
+    using E = ToType<NoThrowConvertible::Yes>;
+    using Expected = iceberg::expected<T, E>;
+    Expected e;
+    EXPECT_TRUE(noexcept(e.error_or(FromType{})));
+  }
+  {  // noexcept(false)
+    using T = int;
+    using E = ToType<NoThrowConvertible::No>;
+    using Expected = iceberg::expected<T, E>;
+    Expected e;
+    EXPECT_FALSE(noexcept(e.error_or(FromType{})));
+  }
+}
+
+TEST(ExpectedTest, VoidTErrorOrNoxcept) {
+  {  // noexcept(true)
+    using T = void;
+    using E = ToType<NoThrowConvertible::Yes>;
+    using Expected = iceberg::expected<T, E>;
+    Expected e;
+    EXPECT_TRUE(noexcept(e.error_or(FromType{})));
+  }
+  {  // noexcept(false)
+    using T = void;
+    using E = ToType<NoThrowConvertible::No>;
+    using Expected = iceberg::expected<T, E>;
+    Expected e;
+    EXPECT_FALSE(noexcept(e.error_or(FromType{})));
+  }
+}

From c70f58154535c1739744a6bcf2e76837393dbc5d Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Thu, 10 Sep 2026 16:11:49 +0800
Subject: [PATCH 02/14] let iceberg::expected hold a value type with no default
 constructor

---
 src/iceberg/test/expected_test.cc | 48 +++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/src/iceberg/test/expected_test.cc b/src/iceberg/test/expected_test.cc
index d053b104e..c762b16b2 100644
--- a/src/iceberg/test/expected_test.cc
+++ b/src/iceberg/test/expected_test.cc
@@ -19,6 +19,9 @@
 
 #include "iceberg/expected.h"
 
+#include <functional>
+#include <type_traits>
+
 #include <gtest/gtest.h>
 
 TEST(ExpectedTest, DefaultCons) {
@@ -57,6 +60,50 @@ TEST(ExpectedTest, ImplicitConversionFrom) {
   EXPECT_FALSE((std::is_convertible_v<iceberg::expected<std::string, int>, int>));
 }
 
+TEST(ExpectedTest, ConversionToValueWithoutDefaultConstructor) {
+  int value = 42;
+  iceberg::expected<std::reference_wrapper<int>, int> ref = std::ref(value);
+
+  iceberg::expected<std::reference_wrapper<const int>, int> from_value = ref;
+  ASSERT_TRUE(from_value.has_value());
+  EXPECT_EQ(from_value->get(), 42);
+
+  iceberg::expected<std::reference_wrapper<const int>, int> from_error =
+      iceberg::expected<std::reference_wrapper<int>, int>{iceberg::unexpect, 7};
+  ASSERT_FALSE(from_error.has_value());
+  EXPECT_EQ(from_error.error(), 7);
+
+  EXPECT_FALSE((std::is_default_constructible_v<
+                iceberg::expected<std::reference_wrapper<int>, int>>));
+}
+
+namespace {
+
+// Counts live objects, to catch a value constructed without being destroyed.
+struct LiveCount {
+  static inline int live = 0;
+  LiveCount() { ++live; }
+  explicit LiveCount(int) { ++live; }
+  LiveCount(const LiveCount&) { ++live; }
+  LiveCount(LiveCount&&) noexcept { ++live; }
+  LiveCount& operator=(const LiveCount&) = default;
+  LiveCount& operator=(LiveCount&&) noexcept = default;
+  ~LiveCount() { --live; }
+};
+
+}  // namespace
+
+TEST(ExpectedTest, ConversionConstructsValueOnce) {
+  {
+    iceberg::expected<int, int> value = 1;
+    iceberg::expected<LiveCount, int> from_value(value);
+    iceberg::expected<int, int> error = iceberg::unexpected(2);
+    iceberg::expected<LiveCount, int> from_error(error);
+    EXPECT_EQ(LiveCount::live, 1);
+  }
+  EXPECT_EQ(LiveCount::live, 0);
+}
+
 TEST(ExpectedTest, ExplictVoidE) {
   iceberg::expected<void, int> e1 = {};
   iceberg::expected<void, int> e2 = iceberg::unexpected{42};
@@ -634,3 +681,4 @@ TEST(ExpectedTest, VoidTErrorOrNoxcept) {
     EXPECT_FALSE(noexcept(e.error_or(FromType{})));
   }
 }
+

From 39d76092fb447ed2ec90f1bc8487617cac4ca508 Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Wed, 16 Sep 2026 16:21:06 +0800
Subject: [PATCH 03/14] make Result portable by aliasing it to
 iceberg::expected

---
 src/iceberg/logging/logger.h       |  2 +-
 src/iceberg/result.h               | 12 ++++++------
 src/iceberg/util/error_collector.h |  2 +-
 src/iceberg/util/macros.h          |  2 +-
 src/iceberg/util/stream.h          |  4 ++--
 5 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/src/iceberg/logging/logger.h b/src/iceberg/logging/logger.h
index 8575158ca..35495cf97 100644
--- a/src/iceberg/logging/logger.h
+++ b/src/iceberg/logging/logger.h
@@ -157,7 +157,7 @@ class ICEBERG_EXPORT Logger {
       const std::unordered_map<std::string, std::string>& properties) {
     if (auto it = properties.find(std::string(kLevelProperty)); it != properties.end()) {
       auto parsed = LogLevelFromString(it->second);
-      if (!parsed) return std::unexpected(parsed.error());
+      if (!parsed) return unexpected(parsed.error());
       SetLevel(*parsed);
     }
     return {};
diff --git a/src/iceberg/result.h b/src/iceberg/result.h
index 88b13c51e..ce56b1bb9 100644
--- a/src/iceberg/result.h
+++ b/src/iceberg/result.h
@@ -23,11 +23,11 @@
 /// \brief Define Result, Status, and error helpers.
 
 #include <concepts>
-#include <expected>
 #include <format>
 #include <string>
 #include <type_traits>
 
+#include "iceberg/expected.h"
 #include "iceberg/iceberg_export.h"
 
 namespace iceberg {
@@ -85,7 +85,7 @@ struct DefaultError {
 
 /// \brief Result alias
 template <typename T, typename E = typename DefaultError<T>::type>
-using Result = std::expected<T, E>;
+using Result = expected<T, E>;
 
 using Status = Result<void>;
 
@@ -93,12 +93,12 @@ using Status = Result<void>;
 #define DEFINE_ERROR_FUNCTION(name)                                           \
   template <typename... Args>                                                 \
   inline auto name(const std::format_string<Args...> fmt, Args&&... args)     \
-      -> std::unexpected<Error> {                                             \
-    return std::unexpected<Error>(                                            \
+      -> unexpected<Error> {                                                  \
+    return unexpected<Error>(                                                 \
         {ErrorKind::k##name, std::format(fmt, std::forward<Args>(args)...)}); \
   }                                                                           \
-  inline auto name(std::string message) -> std::unexpected<Error> {           \
-    return std::unexpected<Error>({ErrorKind::k##name, std::move(message)});  \
+  inline auto name(std::string message) -> unexpected<Error> {                \
+    return unexpected<Error>({ErrorKind::k##name, std::move(message)});       \
   }
 
 DEFINE_ERROR_FUNCTION(AlreadyExists)
diff --git a/src/iceberg/util/error_collector.h b/src/iceberg/util/error_collector.h
index 7e8ab218b..08c09ad9a 100644
--- a/src/iceberg/util/error_collector.h
+++ b/src/iceberg/util/error_collector.h
@@ -138,7 +138,7 @@ class ICEBERG_EXPORT ErrorCollector {
   /// \param self Deduced reference to the derived class instance
   /// \param err The unexpected result containing the error to add
   /// \return Reference to the derived class for method chaining
-  auto& AddError(this auto& self, std::unexpected<Error> err) {
+  auto& AddError(this auto& self, unexpected<Error> err) {
     self.errors_.push_back(std::move(err.error()));
     return self;
   }
diff --git a/src/iceberg/util/macros.h b/src/iceberg/util/macros.h
index 400573d8b..ca481a939 100644
--- a/src/iceberg/util/macros.h
+++ b/src/iceberg/util/macros.h
@@ -29,7 +29,7 @@
 
 #define ICEBERG_RETURN_UNEXPECTED(expr)                       \
   if (auto&& result_name = expr; !result_name) [[unlikely]] { \
-    return std::unexpected<Error>(result_name.error());       \
+    return iceberg::unexpected<Error>(result_name.error());   \
   }
 
 #define ICEBERG_ASSIGN_OR_RAISE_IMPL(result_name, lhs, rexpr) \
diff --git a/src/iceberg/util/stream.h b/src/iceberg/util/stream.h
index 97ab07be1..fc01e98c0 100644
--- a/src/iceberg/util/stream.h
+++ b/src/iceberg/util/stream.h
@@ -68,7 +68,7 @@ class Stream {
   /// terminal result without invoking NextImpl().
   Result<std::optional<T>> Next() {
     if (error_.has_value()) {
-      return std::unexpected(*error_);
+      return unexpected(*error_);
     }
     if (finished_) {
       return std::nullopt;
@@ -90,7 +90,7 @@ class Stream {
       while (true) {
         auto result = Next();
         if (!result.has_value()) {
-          return std::unexpected(std::move(result.error()));
+          return unexpected(std::move(result.error()));
         }
         auto& value = result.value();
         if (!value.has_value()) {

From 0bfd6feeb15e5f9f0df5bfab280eb753c8475f5c Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Thu, 10 Sep 2026 15:54:27 +0800
Subject: [PATCH 04/14] replace the remaining C++23 library features in public
 headers

---
 src/iceberg/file_format.h              |  3 +-
 src/iceberg/logging/log_level.h        |  3 +-
 src/iceberg/manifest/manifest_entry.h  |  3 +-
 src/iceberg/manifest/manifest_list.h   |  3 +-
 src/iceberg/metrics/counter.h          |  3 +-
 src/iceberg/metrics/metrics_reporter.h |  3 +-
 src/iceberg/metrics/timer.h            |  3 +-
 src/iceberg/snapshot.h                 |  3 +-
 src/iceberg/transform.h                |  3 +-
 src/iceberg/util/endian.h              | 38 ++++++++++++++++++++++---
 src/iceberg/util/string_util.h         | 11 ++++++--
 src/iceberg/util/unreachable.h         | 39 ++++++++++++++++++++++++++
 src/iceberg/util/visit_type.h          |  3 +-
 13 files changed, 101 insertions(+), 17 deletions(-)
 create mode 100644 src/iceberg/util/unreachable.h

diff --git a/src/iceberg/file_format.h b/src/iceberg/file_format.h
index 0919cf0bf..1541b61d3 100644
--- a/src/iceberg/file_format.h
+++ b/src/iceberg/file_format.h
@@ -28,6 +28,7 @@
 #include "iceberg/iceberg_export.h"
 #include "iceberg/result.h"
 #include "iceberg/util/string_util.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -51,7 +52,7 @@ ICEBERG_EXPORT inline std::string_view ToString(FileFormatType format_type) {
     case FileFormatType::kPuffin:
       return "puffin";
   }
-  std::unreachable();
+  Unreachable();
 }
 
 /// \brief Convert a string to a FileFormatType
diff --git a/src/iceberg/logging/log_level.h b/src/iceberg/logging/log_level.h
index d06916af0..551cc9216 100644
--- a/src/iceberg/logging/log_level.h
+++ b/src/iceberg/logging/log_level.h
@@ -27,6 +27,7 @@
 
 #include "iceberg/result.h"
 #include "iceberg/util/string_util.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -66,7 +67,7 @@ constexpr std::string_view ToString(LogLevel level) noexcept {
     case LogLevel::kOff:
       return "off";
   }
-  std::unreachable();
+  Unreachable();
 }
 
 /// \brief Parse a LogLevel from a string (case-insensitive).
diff --git a/src/iceberg/manifest/manifest_entry.h b/src/iceberg/manifest/manifest_entry.h
index d3dc2f7a2..e29eded99 100644
--- a/src/iceberg/manifest/manifest_entry.h
+++ b/src/iceberg/manifest/manifest_entry.h
@@ -34,6 +34,7 @@
 #include "iceberg/row/partition_values.h"
 #include "iceberg/schema_field.h"
 #include "iceberg/type.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -418,7 +419,7 @@ ICEBERG_EXPORT constexpr std::string_view ToString(DataFile::Content type) noexc
     case DataFile::Content::kEqualityDeletes:
       return "equality_deletes";
   }
-  std::unreachable();
+  Unreachable();
 }
 
 /// \brief Get the relative data file content type from int
diff --git a/src/iceberg/manifest/manifest_list.h b/src/iceberg/manifest/manifest_list.h
index c6b0b7a45..7488628be 100644
--- a/src/iceberg/manifest/manifest_list.h
+++ b/src/iceberg/manifest/manifest_list.h
@@ -34,6 +34,7 @@
 #include "iceberg/schema_field.h"
 #include "iceberg/table_metadata.h"
 #include "iceberg/type.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -264,7 +265,7 @@ ICEBERG_EXPORT inline constexpr std::string_view ToString(ManifestContent type)
     case ManifestContent::kDeletes:
       return "deletes";
   }
-  std::unreachable();
+  Unreachable();
 }
 
 /// \brief Get the relative manifest content type from name
diff --git a/src/iceberg/metrics/counter.h b/src/iceberg/metrics/counter.h
index b44cf844b..96f7de13d 100644
--- a/src/iceberg/metrics/counter.h
+++ b/src/iceberg/metrics/counter.h
@@ -31,6 +31,7 @@
 #include "iceberg/iceberg_export.h"
 #include "iceberg/result.h"
 #include "iceberg/util/string_util.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -51,7 +52,7 @@ ICEBERG_EXPORT constexpr std::string_view ToString(CounterUnit unit) noexcept {
     case CounterUnit::kUndefined:
       return "undefined";
   }
-  std::unreachable();
+  Unreachable();
 }
 
 /// \brief Parse a CounterUnit from a string.
diff --git a/src/iceberg/metrics/metrics_reporter.h b/src/iceberg/metrics/metrics_reporter.h
index a45754dc0..b49b86ae8 100644
--- a/src/iceberg/metrics/metrics_reporter.h
+++ b/src/iceberg/metrics/metrics_reporter.h
@@ -32,6 +32,7 @@
 #include "iceberg/metrics/commit_report.h"
 #include "iceberg/metrics/scan_report.h"
 #include "iceberg/result.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -49,7 +50,7 @@ ICEBERG_EXPORT constexpr std::string_view ToString(MetricsReportType type) noexc
     case MetricsReportType::kCommitReport:
       return "commit";
   }
-  std::unreachable();
+  Unreachable();
 }
 
 /// \brief A metrics report, which can be either a ScanReport or CommitReport.
diff --git a/src/iceberg/metrics/timer.h b/src/iceberg/metrics/timer.h
index e15c623f3..9303b3bce 100644
--- a/src/iceberg/metrics/timer.h
+++ b/src/iceberg/metrics/timer.h
@@ -32,6 +32,7 @@
 #include <utility>
 
 #include "iceberg/iceberg_export.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -64,7 +65,7 @@ ICEBERG_EXPORT constexpr std::string_view ToString(TimerUnit unit) noexcept {
     case TimerUnit::kDays:
       return "days";
   }
-  std::unreachable();
+  Unreachable();
 }
 
 /// \brief Abstract timer for measuring operation durations.
diff --git a/src/iceberg/snapshot.h b/src/iceberg/snapshot.h
index 4ac600c55..aa54a6e49 100644
--- a/src/iceberg/snapshot.h
+++ b/src/iceberg/snapshot.h
@@ -36,6 +36,7 @@
 #include "iceberg/type_fwd.h"
 #include "iceberg/util/lazy.h"
 #include "iceberg/util/timepoint.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -57,7 +58,7 @@ ICEBERG_EXPORT constexpr std::string_view ToString(SnapshotRefType type) noexcep
     case SnapshotRefType::kTag:
       return "tag";
   }
-  std::unreachable();
+  Unreachable();
 }
 /// \brief Get the relative snapshot reference type from name
 ICEBERG_EXPORT constexpr Result<SnapshotRefType> SnapshotRefTypeFromString(
diff --git a/src/iceberg/transform.h b/src/iceberg/transform.h
index 0228c020a..ea97779ac 100644
--- a/src/iceberg/transform.h
+++ b/src/iceberg/transform.h
@@ -32,6 +32,7 @@
 #include "iceberg/result.h"
 #include "iceberg/type_fwd.h"
 #include "iceberg/util/formattable.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -80,7 +81,7 @@ ICEBERG_EXPORT constexpr std::string_view TransformTypeToString(TransformType ty
     case TransformType::kVoid:
       return "void";
   }
-  std::unreachable();
+  Unreachable();
 }
 
 /// \brief Represents a transform used in partitioning or sorting in Iceberg.
diff --git a/src/iceberg/util/endian.h b/src/iceberg/util/endian.h
index 8aa559f40..81f1a40e0 100644
--- a/src/iceberg/util/endian.h
+++ b/src/iceberg/util/endian.h
@@ -21,14 +21,43 @@
 
 #include <bit>
 #include <concepts>
+#include <cstddef>
 #include <cstdint>
 #include <cstring>
+#include <type_traits>
 
 /// \file iceberg/util/endian.h
 /// \brief Endianness conversion utilities
 
 namespace iceberg {
 
+namespace internal {
+
+// std::byteswap is C++23 and this header is public. GCC and Clang provide the same
+// swap as builtins, which are usable in constant expressions and compile to a
+// single instruction at any optimization level; other compilers reverse the bytes
+// by hand.
+template <std::unsigned_integral T>
+constexpr T ByteSwapUnsigned(T value) {
+#if defined(__GNUC__) || defined(__clang__)
+  if constexpr (sizeof(T) == sizeof(uint16_t)) {
+    return static_cast<T>(__builtin_bswap16(value));
+  } else if constexpr (sizeof(T) == sizeof(uint32_t)) {
+    return static_cast<T>(__builtin_bswap32(value));
+  } else if constexpr (sizeof(T) == sizeof(uint64_t)) {
+    return static_cast<T>(__builtin_bswap64(value));
+  }
+#endif
+  T swapped{0};
+  for (size_t byte = 0; byte < sizeof(T); ++byte) {
+    swapped = static_cast<T>(swapped << 8) | static_cast<T>(value & 0xFF);
+    value = static_cast<T>(value >> 8);
+  }
+  return swapped;
+}
+
+}  // namespace internal
+
 /// \brief Concept for values that can be converted to/from another endian format.
 template <typename T>
 concept EndianConvertible = std::is_arithmetic_v<T>;
@@ -40,14 +69,15 @@ constexpr T ByteSwap(T value) {
   if constexpr (sizeof(T) <= 1) {
     return value;
   } else if constexpr (std::is_integral_v<T>) {
-    return std::byteswap(value);
+    return static_cast<T>(
+        internal::ByteSwapUnsigned(static_cast<std::make_unsigned_t<T>>(value)));
   } else if constexpr (std::is_floating_point_v<T>) {
     if constexpr (sizeof(T) == sizeof(uint16_t)) {
-      return std::bit_cast<T>(std::byteswap(std::bit_cast<uint16_t>(value)));
+      return std::bit_cast<T>(internal::ByteSwapUnsigned(std::bit_cast<uint16_t>(value)));
     } else if constexpr (sizeof(T) == sizeof(uint32_t)) {
-      return std::bit_cast<T>(std::byteswap(std::bit_cast<uint32_t>(value)));
+      return std::bit_cast<T>(internal::ByteSwapUnsigned(std::bit_cast<uint32_t>(value)));
     } else if constexpr (sizeof(T) == sizeof(uint64_t)) {
-      return std::bit_cast<T>(std::byteswap(std::bit_cast<uint64_t>(value)));
+      return std::bit_cast<T>(internal::ByteSwapUnsigned(std::bit_cast<uint64_t>(value)));
     } else {
       static_assert(sizeof(T) == 0,
                     "Unsupported floating-point size for endian conversion.");
diff --git a/src/iceberg/util/string_util.h b/src/iceberg/util/string_util.h
index 2559b47a3..60ee7ef8f 100644
--- a/src/iceberg/util/string_util.h
+++ b/src/iceberg/util/string_util.h
@@ -36,6 +36,7 @@
 
 #include "iceberg/iceberg_export.h"
 #include "iceberg/result.h"
+#include "iceberg/util/unreachable.h"
 
 namespace iceberg {
 
@@ -70,8 +71,12 @@ class ICEBERG_EXPORT StringUtils {
   /// simple case mapping would be wrong for some letters (e.g. "ß" (U+00DF) would stay
   /// unchanged instead of becoming "SS"), and no caller needs it.
   static std::string ToUpper(std::string_view str) {
-    return str | std::ranges::views::transform(ToUpperAscii) |
-           std::ranges::to<std::string>();
+    std::string upper;
+    upper.reserve(str.size());
+    for (char ch : str) {
+      upper.push_back(ToUpperAscii(ch));
+    }
+    return upper;
   }
 
   /// \brief Case-insensitive equality using Unicode simple (1:1) case mapping.
@@ -132,7 +137,7 @@ class ICEBERG_EXPORT StringUtils {
       return InvalidArgument("Failed to parse {} from string '{}': value out of range",
                              typeid(T).name(), str);
     }
-    std::unreachable();
+    Unreachable();
   }
 
   /// \brief Decode a hex string (upper or lower case) into bytes.
diff --git a/src/iceberg/util/unreachable.h b/src/iceberg/util/unreachable.h
new file mode 100644
index 000000000..428426f56
--- /dev/null
+++ b/src/iceberg/util/unreachable.h
@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+/// \file iceberg/util/unreachable.h
+/// \brief Portable stand-in for std::unreachable.
+
+namespace iceberg {
+
+/// \brief Marks a branch the program can never take.
+///
+/// Reaching it is undefined behavior, as with std::unreachable. That is C++23,
+/// so it cannot appear in a header a C++20 consumer includes.
+[[noreturn]] inline void Unreachable() {
+#if defined(_MSC_VER) && !defined(__clang__)
+  __assume(false);
+#else
+  __builtin_unreachable();
+#endif
+}
+
+}  // namespace iceberg
diff --git a/src/iceberg/util/visit_type.h b/src/iceberg/util/visit_type.h
index 73fbbb5fd..c49361431 100644
--- a/src/iceberg/util/visit_type.h
+++ b/src/iceberg/util/visit_type.h
@@ -29,6 +29,7 @@
 #include "iceberg/result.h"
 #include "iceberg/type.h"
 #include "iceberg/util/checked_cast.h"
+#include "iceberg/util/unreachable.h"
 #include "iceberg/util/visitor_generate.h"
 
 namespace iceberg {
@@ -94,7 +95,7 @@ inline auto VisitType(const Type& type, VISITOR&& visitor, ARGS&&... args)
   switch (type.type_id()) {
     ICEBERG_GENERATE_FOR_ALL_TYPES(TYPE_VISIT_INLINE);
     default:
-      std::unreachable();
+      Unreachable();
   }
 }
 

From 350816b3972015dc5ebbdf7d394f34122c46c1fa Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Thu, 10 Sep 2026 15:54:54 +0800
Subject: [PATCH 05/14] drop deducing this from TaskGroup

---
 src/iceberg/util/task_group.h | 49 ++++++++++++++++++++++++-----------
 1 file changed, 34 insertions(+), 15 deletions(-)

diff --git a/src/iceberg/util/task_group.h b/src/iceberg/util/task_group.h
index 3d345c240..5be18ab7d 100644
--- a/src/iceberg/util/task_group.h
+++ b/src/iceberg/util/task_group.h
@@ -73,26 +73,30 @@ class ICEBERG_TEMPLATE_CLASS_EXPORT TaskGroup {
     requires(kRetryEnabled)
       : retry_config_(std::move(retry_config)) {}
 
-  auto&& SetExecutor(this auto&& self, OptionalExecutor executor) {
-    self.executor_ = std::move(executor);
-    return std::forward<decltype(self)>(self);
+  TaskGroup& SetExecutor(OptionalExecutor executor) & {
+    executor_ = std::move(executor);
+    return *this;
+  }
+
+  TaskGroup&& SetExecutor(OptionalExecutor executor) && {
+    executor_ = std::move(executor);
+    return std::move(*this);
   }
 
   template <typename F>
     requires((!kRetryEnabled && internal::OnceStatusTask<F>) ||
              (kRetryEnabled && internal::RetryableStatusTask<F>))
-  auto&& Submit(this auto&& self, F&& task) {
-    self.tasks_.emplace_back([&] {
-      if constexpr (!kRetryEnabled) {
-        return std::forward<F>(task);
-      } else {
-        return [retry_config = self.retry_config_,
-                task = std::forward<F>(task)]() mutable -> Status {
-          return RetryRunner<RetryPolicy>(retry_config).Run(task);
-        };
-      }
-    }());
-    return std::forward<decltype(self)>(self);
+  TaskGroup& Submit(F&& task) & {
+    AddTask(std::forward<F>(task));
+    return *this;
+  }
+
+  template <typename F>
+    requires((!kRetryEnabled && internal::OnceStatusTask<F>) ||
+             (kRetryEnabled && internal::RetryableStatusTask<F>))
+  TaskGroup&& Submit(F&& task) && {
+    AddTask(std::forward<F>(task));
+    return std::move(*this);
   }
 
   Status Run() && {
@@ -103,6 +107,21 @@ class ICEBERG_TEMPLATE_CLASS_EXPORT TaskGroup {
   }
 
  private:
+  // Shared by both Submit overloads.
+  template <typename F>
+  void AddTask(F&& task) {
+    tasks_.emplace_back([&] {
+      if constexpr (!kRetryEnabled) {
+        return std::forward<F>(task);
+      } else {
+        return [retry_config = retry_config_,
+                task = std::forward<F>(task)]() mutable -> Status {
+          return RetryRunner<RetryPolicy>(retry_config).Run(task);
+        };
+      }
+    }());
+  }
+
   std::vector<FnOnce<Status()>> tasks_;
   OptionalExecutor executor_;
   [[no_unique_address]] RetryConfigStorage retry_config_;

From a7e8b010b795cac5dd85474d5ed33a642d64f81c Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Wed, 16 Sep 2026 16:22:10 +0800
Subject: [PATCH 06/14] give ErrorCollector::AddError a C++20 form

---
 src/iceberg/util/error_collector.h | 56 ++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 7 deletions(-)

diff --git a/src/iceberg/util/error_collector.h b/src/iceberg/util/error_collector.h
index 08c09ad9a..85f652cbc 100644
--- a/src/iceberg/util/error_collector.h
+++ b/src/iceberg/util/error_collector.h
@@ -48,7 +48,8 @@ namespace iceberg {
 #define ICEBERG_BUILDER_ASSIGN_OR_RETURN_WITH_ERROR_IMPL(result_name, lhs, rexpr, ...) \
   auto&& result_name = (rexpr);                                                        \
   if (!result_name) [[unlikely]] {                                                     \
-    return AddError(ErrorKind::kInvalidArgument, __VA_ARGS__);                         \
+    AddError(ErrorKind::kInvalidArgument, __VA_ARGS__);                                \
+    return *this;                                                                      \
   }                                                                                    \
   lhs = std::move(result_name.value());
 
@@ -56,11 +57,12 @@ namespace iceberg {
   ICEBERG_BUILDER_ASSIGN_OR_RETURN_WITH_ERROR_IMPL(                  \
       ICEBERG_ASSIGN_OR_RAISE_NAME(result_, __COUNTER__), lhs, rexpr, __VA_ARGS__)
 
-#define ICEBERG_BUILDER_CHECK(expr, ...)                         \
-  do {                                                           \
-    if (!(expr)) [[unlikely]] {                                  \
-      return AddError(ErrorKind::kInvalidArgument, __VA_ARGS__); \
-    }                                                            \
+#define ICEBERG_BUILDER_CHECK(expr, ...)                  \
+  do {                                                    \
+    if (!(expr)) [[unlikely]] {                           \
+      AddError(ErrorKind::kInvalidArgument, __VA_ARGS__); \
+      return *this;                                       \
+    }                                                     \
   } while (false)
 
 /// \brief Base class for collecting errors in the builder pattern.
@@ -75,7 +77,8 @@ namespace iceberg {
 ///    public:
 ///     MyBuilder& SetValue(int val) {
 ///       if (val < 0) {
-///         return AddError(ErrorKind::kInvalidArgument, "Value must be non-negative");
+///         AddError(ErrorKind::kInvalidArgument, "Value must be non-negative");
+///         return *this;
 ///       }
 ///       value_ = val;
 ///       return *this;
@@ -101,6 +104,13 @@ class ICEBERG_EXPORT ErrorCollector {
   ErrorCollector(const ErrorCollector&) = default;
   ErrorCollector& operator=(const ErrorCollector&) = default;
 
+// C++23 uses deducing `this` so that `return AddError(...)` keeps returning the
+// derived builder type. C++20 exposes the same overloads returning ErrorCollector&,
+// because preserving the derived type would require making the builders CRTP. Keyed
+// on the language version rather than __cpp_explicit_this_parameter, which Apple
+// clang does not define, and compared with "> 202002L" because MSVC's
+// /std:c++latest only promises a value above 202002L.
+#if __cplusplus > 202002L || (defined(_MSVC_LANG) && _MSVC_LANG > 202002L)
   /// \brief Add a specific error and return reference to derived class
   ///
   /// \param self Deduced reference to the derived class instance
@@ -142,6 +152,38 @@ class ICEBERG_EXPORT ErrorCollector {
     self.errors_.push_back(std::move(err.error()));
     return self;
   }
+#else
+  /// \brief Add a specific error
+  ///
+  /// \param kind The kind of error
+  /// \param fmt The format string
+  /// \param args The arguments to format the message
+  /// \return This error collector for method chaining
+  template <typename... Args>
+  ErrorCollector& AddError(ErrorKind kind, const std::format_string<Args...> fmt,
+                           Args&&... args) {
+    errors_.emplace_back(kind, std::format(fmt, std::forward<Args>(args)...));
+    return *this;
+  }
+
+  /// \brief Add an existing error object
+  ///
+  /// \param err The error to add
+  /// \return This error collector for method chaining
+  ErrorCollector& AddError(Error err) {
+    errors_.push_back(std::move(err));
+    return *this;
+  }
+
+  /// \brief Add an unexpected result's error
+  ///
+  /// \param err The unexpected result containing the error to add
+  /// \return This error collector for method chaining
+  ErrorCollector& AddError(unexpected<Error> err) {
+    errors_.push_back(std::move(err.error()));
+    return *this;
+  }
+#endif  // C++23
 
   /// \brief Check if any errors have been collected
   ///

From 65c7fd70c53432df94db2f4a06f34c9a3d545e2c Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Wed, 16 Sep 2026 16:22:24 +0800
Subject: [PATCH 07/14] give SnapshotUpdate's chaining setters a C++20 form

---
 src/iceberg/update/snapshot_update.h | 100 +++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/src/iceberg/update/snapshot_update.h b/src/iceberg/update/snapshot_update.h
index 3537bd7d9..c3b33b8de 100644
--- a/src/iceberg/update/snapshot_update.h
+++ b/src/iceberg/update/snapshot_update.h
@@ -62,6 +62,13 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
   bool IsRetryable() const override { return true; }
   Status Commit() override;
 
+// C++23 uses deducing `this` so chaining keeps returning the derived update type.
+// C++20 exposes the same operations but returns SnapshotUpdate&, because preserving
+// the derived type would require making the update hierarchy CRTP. Keyed on the
+// language version rather than __cpp_explicit_this_parameter, which Apple clang does
+// not define, and compared with "> 202002L" because MSVC's /std:c++latest only
+// promises a value above 202002L.
+#if __cplusplus > 202002L || (defined(_MSVC_LANG) && _MSVC_LANG > 202002L)
   /// \brief Set the metrics reporter for this snapshot update.
   ///
   /// \param reporter The metrics reporter to use.
@@ -156,6 +163,99 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
     self.write_manifest_parallelism_ = parallelism;
     return self;
   }
+#else
+  /// \brief Set the metrics reporter for this snapshot update.
+  ///
+  /// \param reporter The metrics reporter to use.
+  /// \return This snapshot update for method chaining.
+  SnapshotUpdate& ReportWith(std::shared_ptr<MetricsReporter> reporter) {
+    reporter_ = std::move(reporter);
+    return *this;
+  }
+
+  /// \brief Set a callback to delete files instead of the table's default.
+  ///
+  /// \param delete_func A function used to delete file locations.
+  /// \return This snapshot update for method chaining.
+  /// \note Cannot be called more than once.
+  SnapshotUpdate& DeleteWith(std::function<Status(const std::string&)> delete_func) {
+    if (delete_func_) {
+      AddError(ErrorKind::kInvalidArgument, "Cannot set delete callback more than once");
+      return *this;
+    }
+    delete_func_ = std::move(delete_func);
+    return *this;
+  }
+
+  /// \brief Stage a snapshot in table metadata, but do not make it current.
+  ///
+  /// \return This snapshot update for method chaining.
+  SnapshotUpdate& StageOnly() {
+    stage_only_ = true;
+    return *this;
+  }
+
+  /// \brief Configure an executor for manifest planning work.
+  ///
+  /// \param executor Executor to use while planning manifests.
+  /// \return This snapshot update for method chaining.
+  SnapshotUpdate& ScanManifestsWith(Executor& executor) {
+    plan_executor_ = std::ref(executor);
+    return *this;
+  }
+
+  /// \brief Perform operations on a particular branch.
+  ///
+  /// \param branch The name of a SnapshotRef of type branch.
+  /// \return This snapshot update for method chaining.
+  SnapshotUpdate& ToBranch(const std::string& branch) {
+    if (branch.empty()) [[unlikely]] {
+      AddError(ErrorKind::kInvalidArgument, "Branch name cannot be empty");
+      return *this;
+    }
+
+    if (auto ref_it = base().refs.find(branch); ref_it != base().refs.end()) {
+      if (ref_it->second->type() != SnapshotRefType::kBranch) {
+        AddError(ErrorKind::kInvalidArgument,
+                 "{} is a tag, not a branch. Tags cannot be targets for "
+                 "producing snapshots",
+                 branch);
+        return *this;
+      }
+    }
+
+    target_branch_ = branch;
+    return *this;
+  }
+
+  /// \brief Set a summary property in the snapshot produced by this update.
+  ///
+  /// \param property A String property name.
+  /// \param value A String property value.
+  /// \return This snapshot update for method chaining.
+  SnapshotUpdate& Set(const std::string& property, const std::string& value) {
+    SetSummaryProperty(property, value);
+    return *this;
+  }
+
+  /// \brief Configure an executor and max writer count for writing new manifests.
+  ///
+  /// \param executor Executor to use while writing manifests.
+  /// \param parallelism Maximum number of concurrent manifest writers.
+  /// \return This snapshot update for method chaining.
+  SnapshotUpdate& WriteManifestsWith(Executor& executor, int32_t parallelism) {
+    if (parallelism <= 0) [[unlikely]] {
+      AddError(ErrorKind::kInvalidArgument,
+               "Manifest write parallelism must be greater than 0, but was: {}",
+               parallelism);
+      return *this;
+    }
+
+    write_manifest_executor_ = std::ref(executor);
+    write_manifest_parallelism_ = parallelism;
+    return *this;
+  }
+#endif  // C++23
 
  protected:
   friend class Transaction;

From b57c3e5c2646cd7445f4d561fe174164f77d1500 Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Thu, 10 Sep 2026 16:13:43 +0800
Subject: [PATCH 08/14] build the example as C++20

---
 example/CMakeLists.txt | 62 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 57 insertions(+), 5 deletions(-)

diff --git a/example/CMakeLists.txt b/example/CMakeLists.txt
index a9bf73cf0..08915b7e1 100644
--- a/example/CMakeLists.txt
+++ b/example/CMakeLists.txt
@@ -20,13 +20,65 @@ cmake_minimum_required(VERSION 3.25)
 
 project(example)
 
-set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD 20)
 
 find_package(iceberg CONFIG REQUIRED COMPONENTS bundle rest)
 
+if(TARGET iceberg::iceberg_bundle_shared)
+  set(ICEBERG_BUNDLE_TARGET iceberg::iceberg_bundle_shared)
+else()
+  set(ICEBERG_BUNDLE_TARGET iceberg::iceberg_bundle_static)
+endif()
+
+if(TARGET iceberg::iceberg_rest_shared)
+  set(ICEBERG_REST_TARGET iceberg::iceberg_rest_shared)
+else()
+  set(ICEBERG_REST_TARGET iceberg::iceberg_rest_static)
+endif()
+
 add_executable(demo_example demo_example.cc)
 
-target_link_libraries(demo_example
-                      PRIVATE "$<IF:$<TARGET_EXISTS:iceberg::iceberg_bundle_shared>,iceberg::iceberg_bundle_shared,iceberg::iceberg_bundle_static>"
-                              "$<IF:$<TARGET_EXISTS:iceberg::iceberg_rest_shared>,iceberg::iceberg_rest_shared,iceberg::iceberg_rest_static>"
-)
+target_link_libraries(demo_example PRIVATE ${ICEBERG_BUNDLE_TARGET}
+                                           ${ICEBERG_REST_TARGET})
+
+# Compile every installed public header as a C++20 consumer. The installed include
+# tree is the public API contract: iceberg_install_all_headers excludes internal
+# headers before packaging them.
+get_target_property(ICEBERG_BUNDLE_INCLUDE_DIRS ${ICEBERG_BUNDLE_TARGET}
+                    INTERFACE_INCLUDE_DIRECTORIES)
+foreach(ICEBERG_INCLUDE_DIR IN LISTS ICEBERG_BUNDLE_INCLUDE_DIRS)
+  if(EXISTS "${ICEBERG_INCLUDE_DIR}/iceberg")
+    set(ICEBERG_PUBLIC_INCLUDE_DIR "${ICEBERG_INCLUDE_DIR}")
+    break()
+  endif()
+endforeach()
+
+if(NOT ICEBERG_PUBLIC_INCLUDE_DIR)
+  message(FATAL_ERROR "Could not locate iceberg's installed public headers")
+endif()
+
+file(GLOB_RECURSE ICEBERG_PUBLIC_HEADERS CONFIGURE_DEPENDS
+     "${ICEBERG_PUBLIC_INCLUDE_DIR}/iceberg/*.h"
+     "${ICEBERG_PUBLIC_INCLUDE_DIR}/iceberg/*.hpp")
+list(SORT ICEBERG_PUBLIC_HEADERS)
+
+set(ICEBERG_PUBLIC_HEADER_CHECK_SOURCE
+    "// Generated from iceberg's installed public headers.\n")
+foreach(ICEBERG_PUBLIC_HEADER IN LISTS ICEBERG_PUBLIC_HEADERS)
+  file(RELATIVE_PATH ICEBERG_PUBLIC_HEADER_RELATIVE_PATH
+       "${ICEBERG_PUBLIC_INCLUDE_DIR}" "${ICEBERG_PUBLIC_HEADER}")
+  string(APPEND ICEBERG_PUBLIC_HEADER_CHECK_SOURCE
+         "#include <${ICEBERG_PUBLIC_HEADER_RELATIVE_PATH}>\n")
+endforeach()
+string(APPEND ICEBERG_PUBLIC_HEADER_CHECK_SOURCE "\nint main() { return 0; }\n")
+
+file(GENERATE OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc"
+     CONTENT "${ICEBERG_PUBLIC_HEADER_CHECK_SOURCE}")
+
+add_executable(public_headers_cxx20
+               "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc")
+set_target_properties(public_headers_cxx20 PROPERTIES CXX_STANDARD 20
+                                              CXX_STANDARD_REQUIRED ON
+                                              CXX_EXTENSIONS OFF)
+target_link_libraries(public_headers_cxx20
+                      PRIVATE ${ICEBERG_BUNDLE_TARGET} ${ICEBERG_REST_TARGET})

From 6c0761df56becfa2a2c4fd0583669a8c93a81f1c Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Thu, 17 Sep 2026 11:53:30 +0800
Subject: [PATCH 09/14] Fix pre-commit

---
 example/CMakeLists.txt            | 24 +++++++++++++-----------
 src/iceberg/test/expected_test.cc |  1 -
 2 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/example/CMakeLists.txt b/example/CMakeLists.txt
index 08915b7e1..396109e2d 100644
--- a/example/CMakeLists.txt
+++ b/example/CMakeLists.txt
@@ -57,7 +57,9 @@ if(NOT ICEBERG_PUBLIC_INCLUDE_DIR)
   message(FATAL_ERROR "Could not locate iceberg's installed public headers")
 endif()
 
-file(GLOB_RECURSE ICEBERG_PUBLIC_HEADERS CONFIGURE_DEPENDS
+file(GLOB_RECURSE
+     ICEBERG_PUBLIC_HEADERS
+     CONFIGURE_DEPENDS
      "${ICEBERG_PUBLIC_INCLUDE_DIR}/iceberg/*.h"
      "${ICEBERG_PUBLIC_INCLUDE_DIR}/iceberg/*.hpp")
 list(SORT ICEBERG_PUBLIC_HEADERS)
@@ -65,20 +67,20 @@ list(SORT ICEBERG_PUBLIC_HEADERS)
 set(ICEBERG_PUBLIC_HEADER_CHECK_SOURCE
     "// Generated from iceberg's installed public headers.\n")
 foreach(ICEBERG_PUBLIC_HEADER IN LISTS ICEBERG_PUBLIC_HEADERS)
-  file(RELATIVE_PATH ICEBERG_PUBLIC_HEADER_RELATIVE_PATH
-       "${ICEBERG_PUBLIC_INCLUDE_DIR}" "${ICEBERG_PUBLIC_HEADER}")
+  file(RELATIVE_PATH ICEBERG_PUBLIC_HEADER_RELATIVE_PATH "${ICEBERG_PUBLIC_INCLUDE_DIR}"
+       "${ICEBERG_PUBLIC_HEADER}")
   string(APPEND ICEBERG_PUBLIC_HEADER_CHECK_SOURCE
          "#include <${ICEBERG_PUBLIC_HEADER_RELATIVE_PATH}>\n")
 endforeach()
 string(APPEND ICEBERG_PUBLIC_HEADER_CHECK_SOURCE "\nint main() { return 0; }\n")
 
-file(GENERATE OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc"
+file(GENERATE
+     OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc"
      CONTENT "${ICEBERG_PUBLIC_HEADER_CHECK_SOURCE}")
 
-add_executable(public_headers_cxx20
-               "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc")
-set_target_properties(public_headers_cxx20 PROPERTIES CXX_STANDARD 20
-                                              CXX_STANDARD_REQUIRED ON
-                                              CXX_EXTENSIONS OFF)
-target_link_libraries(public_headers_cxx20
-                      PRIVATE ${ICEBERG_BUNDLE_TARGET} ${ICEBERG_REST_TARGET})
+add_executable(public_headers_cxx20 "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc")
+set_target_properties(public_headers_cxx20
+                      PROPERTIES CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON CXX_EXTENSIONS
+                                                                          OFF)
+target_link_libraries(public_headers_cxx20 PRIVATE ${ICEBERG_BUNDLE_TARGET}
+                                                   ${ICEBERG_REST_TARGET})
diff --git a/src/iceberg/test/expected_test.cc b/src/iceberg/test/expected_test.cc
index c762b16b2..76684ac07 100644
--- a/src/iceberg/test/expected_test.cc
+++ b/src/iceberg/test/expected_test.cc
@@ -681,4 +681,3 @@ TEST(ExpectedTest, VoidTErrorOrNoxcept) {
     EXPECT_FALSE(noexcept(e.error_or(FromType{})));
   }
 }
-

From dd8f550bf5246ee787ee67511580f8af62bfef02 Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Thu, 17 Sep 2026 13:01:33 +0800
Subject: [PATCH 10/14] Removed invalid e1.error() access on a successful
 expected<void, int>

---
 src/iceberg/test/expected_test.cc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/iceberg/test/expected_test.cc b/src/iceberg/test/expected_test.cc
index 76684ac07..984bc0601 100644
--- a/src/iceberg/test/expected_test.cc
+++ b/src/iceberg/test/expected_test.cc
@@ -104,13 +104,14 @@ TEST(ExpectedTest, ConversionConstructsValueOnce) {
   EXPECT_EQ(LiveCount::live, 0);
 }
 
-TEST(ExpectedTest, ExplictVoidE) {
+TEST(ExpectedTest, ExplicitVoidE) {
   iceberg::expected<void, int> e1 = {};
   iceberg::expected<void, int> e2 = iceberg::unexpected{42};
 
   EXPECT_TRUE(e1.has_value());
   EXPECT_TRUE((std::is_same_v<decltype(e1.value()), void>));
-  EXPECT_EQ(e1.error(), 0);
+  e1.value();
+  EXPECT_FALSE(e2.has_value());
   EXPECT_EQ(e2.error(), 42);
 }
 

From 2b1bbb292fca8eef274c026f7d84a44ca424349e Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Mon, 21 Sep 2026 09:34:44 +0800
Subject: [PATCH 11/14] Fix windows build

---
 src/iceberg/test/expected_test.cc | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/iceberg/test/expected_test.cc b/src/iceberg/test/expected_test.cc
index 984bc0601..0b7a2314f 100644
--- a/src/iceberg/test/expected_test.cc
+++ b/src/iceberg/test/expected_test.cc
@@ -20,7 +20,9 @@
 #include "iceberg/expected.h"
 
 #include <functional>
+#include <memory>
 #include <type_traits>
+#include <vector>
 
 #include <gtest/gtest.h>
 
@@ -77,6 +79,13 @@ TEST(ExpectedTest, ConversionToValueWithoutDefaultConstructor) {
                 iceberg::expected<std::reference_wrapper<int>, int>>));
 }
 
+TEST(ExpectedTest, SupportsMoveOnlyContainerValue) {
+  using MoveOnlyContainer = std::vector<std::unique_ptr<int>>;
+  iceberg::expected<MoveOnlyContainer, int> value{std::in_place};
+
+  EXPECT_TRUE(value.has_value());
+}
+
 namespace {
 
 // Counts live objects, to catch a value constructed without being destroyed.

From e537167ccfdff01a27df91ebb6bd2c24348fb60a Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Wed, 23 Sep 2026 21:47:40 +0800
Subject: [PATCH 12/14] expose ICEBERG_EXAMPLE_CXX_STANDARD and update docs to
 state C++20 as minimum standard for public headers

---
 .github/workflows/test.yml     | 25 ++++++++++++++++++++++---
 README.md                      | 14 +++++++++++++-
 ci/scripts/build_example.sh    |  2 ++
 example/CMakeLists.txt         | 28 ++++++++++++++++++++--------
 mkdocs/docs/getting-started.md | 14 +++++++++++++-
 mkdocs/docs/index.md           |  2 +-
 6 files changed, 71 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 352da0d7a..524693b87 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -78,12 +78,19 @@ jobs:
         with:
           key-prefix: sccache-test-ubuntu-${{ matrix.cmake_build_type }}
           job-status: ${{ job.status }}
-      - name: Build Example
+      - name: Build Example (C++20)
         shell: bash
         env:
           CC: gcc-14
           CXX: g++-14
         run: ci/scripts/build_example.sh $(pwd)/example
+      - name: Build Example (C++23)
+        shell: bash
+        env:
+          CC: gcc-14
+          CXX: g++-14
+          ICEBERG_EXAMPLE_CXX_STANDARD: 23
+        run: ci/scripts/build_example.sh $(pwd)/example
   hive:
     if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
     name: AMD64 Ubuntu 26.04 Hive
@@ -153,9 +160,14 @@ jobs:
         with:
           key-prefix: sccache-test-macos
           job-status: ${{ job.status }}
-      - name: Build Example
+      - name: Build Example (C++20)
         shell: bash
         run: ci/scripts/build_example.sh $(pwd)/example
+      - name: Build Example (C++23)
+        shell: bash
+        env:
+          ICEBERG_EXAMPLE_CXX_STANDARD: 23
+        run: ci/scripts/build_example.sh $(pwd)/example
   windows:
     if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
     name: AMD64 Windows 2025
@@ -199,8 +211,15 @@ jobs:
         with:
           key-prefix: sccache-test-windows
           job-status: ${{ job.status }}
-      - name: Build Example
+      - name: Build Example (C++20)
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          bash -lc 'ci/scripts/build_example.sh $(pwd)/example'
+      - name: Build Example (C++23)
         shell: pwsh
+        env:
+          ICEBERG_EXAMPLE_CXX_STANDARD: 23
         run: |
           $ErrorActionPreference = "Stop"
           bash -lc 'ci/scripts/build_example.sh $(pwd)/example'
diff --git a/README.md b/README.md
index 920b01a59..9fc61ad43 100644
--- a/README.md
+++ b/README.md
@@ -31,10 +31,14 @@ C++ implementation of [Apache Iceberg™](https://iceberg.apache.org/).
 
 **Required:**
 
-- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+)
+- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+) to build iceberg-cpp itself
 - CMake 3.25+
 - [Ninja](https://ninja-build.org/) (recommended build backend)
 
+**Using iceberg-cpp from your project:** the installed public headers require
+C++20 at minimum, so applications that link against iceberg-cpp can be
+compiled as C++20 or later. The library itself is still built as C++23.
+
 **Optional:**
 
 - Python 3 and [pre-commit](https://pre-commit.com/) (for linting)
@@ -121,6 +125,14 @@ If you are using provided Apache Arrow, include `/path/to/arrow` in `CMAKE_PREFI
 cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH="/path/to/install;/path/to/arrow"
 ```
 
+The examples build as C++20 by default, which is the minimum standard supported
+by the public headers. Set `ICEBERG_EXAMPLE_CXX_STANDARD` to `23` to build them
+as C++23 instead:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/install -DICEBERG_EXAMPLE_CXX_STANDARD=23
+```
+
 ## Customizing Dependency URLs
 
 If you experience network issues when downloading dependencies, you can customize the download URLs using environment variables:
diff --git a/ci/scripts/build_example.sh b/ci/scripts/build_example.sh
index 7ccdf4a8f..386019ad8 100755
--- a/ci/scripts/build_example.sh
+++ b/ci/scripts/build_example.sh
@@ -22,6 +22,7 @@ set -eux
 source_dir=${1}
 build_dir=${1}/build
 run_example=${ICEBERG_RUN_EXAMPLE:-OFF}
+cxx_standard=${ICEBERG_EXAMPLE_CXX_STANDARD:-20}
 
 # Clean up before configuring. If Windows still holds a just-built exe/dll
 # after the retries, let mkdir fail rather than reuse a half-deleted tree.
@@ -53,6 +54,7 @@ fi
 
 build_type="${ICEBERG_BUILD_TYPE:-Debug}"
 CMAKE_ARGS+=("-DCMAKE_BUILD_TYPE=${build_type}")
+CMAKE_ARGS+=("-DICEBERG_EXAMPLE_CXX_STANDARD=${cxx_standard}")
 
 cmake "${CMAKE_ARGS[@]}" ${source_dir}
 cmake --build .
diff --git a/example/CMakeLists.txt b/example/CMakeLists.txt
index 396109e2d..44c599cf8 100644
--- a/example/CMakeLists.txt
+++ b/example/CMakeLists.txt
@@ -20,7 +20,21 @@ cmake_minimum_required(VERSION 3.25)
 
 project(example)
 
-set(CMAKE_CXX_STANDARD 20)
+# C++20 is the minimum standard iceberg-cpp's public headers support, so the
+# example builds as C++20 by default to keep that contract exercised. Set this to
+# 23 to also check the headers from a C++23 consumer.
+set(ICEBERG_EXAMPLE_CXX_STANDARD
+    20
+    CACHE STRING "C++ standard used to build the example (20 or 23)")
+set_property(CACHE ICEBERG_EXAMPLE_CXX_STANDARD PROPERTY STRINGS 20 23)
+if(NOT ICEBERG_EXAMPLE_CXX_STANDARD MATCHES "^(20|23)$")
+  message(FATAL_ERROR "ICEBERG_EXAMPLE_CXX_STANDARD must be 20 or 23, got "
+                      "'${ICEBERG_EXAMPLE_CXX_STANDARD}'")
+endif()
+
+set(CMAKE_CXX_STANDARD ${ICEBERG_EXAMPLE_CXX_STANDARD})
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
 
 find_package(iceberg CONFIG REQUIRED COMPONENTS bundle rest)
 
@@ -41,7 +55,8 @@ add_executable(demo_example demo_example.cc)
 target_link_libraries(demo_example PRIVATE ${ICEBERG_BUNDLE_TARGET}
                                            ${ICEBERG_REST_TARGET})
 
-# Compile every installed public header as a C++20 consumer. The installed include
+# Compile every installed public header as a consumer using
+# ICEBERG_EXAMPLE_CXX_STANDARD. The installed include
 # tree is the public API contract: iceberg_install_all_headers excludes internal
 # headers before packaging them.
 get_target_property(ICEBERG_BUNDLE_INCLUDE_DIRS ${ICEBERG_BUNDLE_TARGET}
@@ -75,12 +90,9 @@ endforeach()
 string(APPEND ICEBERG_PUBLIC_HEADER_CHECK_SOURCE "\nint main() { return 0; }\n")
 
 file(GENERATE
-     OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc"
+     OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/public_headers_check.cc"
      CONTENT "${ICEBERG_PUBLIC_HEADER_CHECK_SOURCE}")
 
-add_executable(public_headers_cxx20 "${CMAKE_CURRENT_BINARY_DIR}/public_headers_cxx20.cc")
-set_target_properties(public_headers_cxx20
-                      PROPERTIES CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON CXX_EXTENSIONS
-                                                                          OFF)
-target_link_libraries(public_headers_cxx20 PRIVATE ${ICEBERG_BUNDLE_TARGET}
+add_executable(public_headers_check "${CMAKE_CURRENT_BINARY_DIR}/public_headers_check.cc")
+target_link_libraries(public_headers_check PRIVATE ${ICEBERG_BUNDLE_TARGET}
                                                    ${ICEBERG_REST_TARGET})
diff --git a/mkdocs/docs/getting-started.md b/mkdocs/docs/getting-started.md
index 89ffd0a0b..fea517e3a 100644
--- a/mkdocs/docs/getting-started.md
+++ b/mkdocs/docs/getting-started.md
@@ -23,10 +23,14 @@
 
 **Required:**
 
-- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+)
+- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+) to build iceberg-cpp itself
 - CMake 3.25+
 - [Ninja](https://ninja-build.org/) (recommended build backend)
 
+**Using iceberg-cpp from your project:** the installed public headers require
+C++20 at minimum, so applications that link against iceberg-cpp can be
+compiled as C++20 or later. The library itself is still built as C++23.
+
 ## Quick Start
 
 ```bash
@@ -112,6 +116,14 @@ If using provided Apache Arrow, include both paths:
 cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH="/path/to/install;/path/to/arrow"
 ```
 
+The examples build as C++20 by default, which is the minimum standard supported
+by the public headers. Set `ICEBERG_EXAMPLE_CXX_STANDARD` to `23` to build them
+as C++23 instead:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/install -DICEBERG_EXAMPLE_CXX_STANDARD=23
+```
+
 ## Customizing Dependency URLs
 
 If you experience network issues when downloading dependencies, you can override the download URLs using environment variables:
diff --git a/mkdocs/docs/index.md b/mkdocs/docs/index.md
index 499583bad..73d92b283 100644
--- a/mkdocs/docs/index.md
+++ b/mkdocs/docs/index.md
@@ -25,7 +25,7 @@ iceberg-cpp is a C++ implementation of [Apache Iceberg™](https://iceberg.apach
 
 ## Key Features
 
-- **Modern C++23** — Built with ranges, concepts, `std::expected`, and other modern idioms
+- **Modern C++** — Built as C++23 with ranges, concepts, and other modern idioms; public headers require only C++20
 - **Cross-Platform** — Builds and runs on Linux, macOS, and Windows
 - **Spec Compliance** — Full table spec support today; Puffin, View, and UDF specs are on the roadmap
 - **Arrow-Native** — Uses the Arrow C Data Interface as the primary data API

From bd71e84fba3816ed850f1a2fdadce7039e13eeb4 Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Mon, 28 Sep 2026 13:59:55 +0800
Subject: [PATCH 13/14] add C++20 public header compatibility check

---
 .github/workflows/cpp-linter.yml             |   4 +-
 .pre-commit-config.yaml                      |   9 +
 README.md                                    |  20 +-
 ci/scripts/generate_public_headers.py        | 129 ++++++++++
 example/CMakeLists.txt                       |  18 +-
 mkdocs/docs/getting-started.md               |  18 +-
 src/iceberg/cpp20_compatibility_internal.h   | 244 +++++++++++++++++++
 src/iceberg/test/CMakeLists.txt              |  52 ++++
 src/iceberg/test/cpp20_compatibility_test.cc |  32 +++
 9 files changed, 505 insertions(+), 21 deletions(-)
 create mode 100755 ci/scripts/generate_public_headers.py
 create mode 100644 src/iceberg/cpp20_compatibility_internal.h
 create mode 100644 src/iceberg/test/cpp20_compatibility_test.cc

diff --git a/.github/workflows/cpp-linter.yml b/.github/workflows/cpp-linter.yml
index 198af3d67..5ca6c4b19 100644
--- a/.github/workflows/cpp-linter.yml
+++ b/.github/workflows/cpp-linter.yml
@@ -103,6 +103,8 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         # need '-fno-builtin-std-forward_like', see https://github.com/llvm/llvm-project/issues/101614
+        # cpp20_compatibility_test.cc is ignored: it asserts it is compiled as C++20,
+        # which the global '-std=c++23' below would override. The build enforces it.
         run: |
           cpp-linter \
             --style='' \
@@ -111,7 +113,7 @@ jobs:
             --files-changed-only=true \
             --lines-changed-only=true \
             --thread-comments=true \
-            --ignore='build|cmake_modules|ci|src/iceberg/catalog/hive/gen-cpp' \
+            --ignore='build|cmake_modules|ci|src/iceberg/catalog/hive/gen-cpp|src/iceberg/test/cpp20_compatibility_test.cc' \
             --database=build \
             --verbosity=debug \
             --extra-arg='-std=c++23' \
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 27ff321da..4aba3e5d6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -43,3 +43,12 @@ repos:
     rev: v0.6.10
     hooks:
       - id: cmake-format
+
+  - repo: local
+    hooks:
+      - id: generate-public-headers
+        name: check src/iceberg/cpp20_compatibility_internal.h is up to date
+        entry: python ci/scripts/generate_public_headers.py
+        language: python
+        files: ^src/.*(\.(h)|CMakeLists\.txt)$
+        pass_filenames: false
diff --git a/README.md b/README.md
index 9fc61ad43..68ecf4500 100644
--- a/README.md
+++ b/README.md
@@ -31,18 +31,28 @@ C++ implementation of [Apache Iceberg™](https://iceberg.apache.org/).
 
 **Required:**
 
-- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+) to build iceberg-cpp itself
+- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+)
 - CMake 3.25+
 - [Ninja](https://ninja-build.org/) (recommended build backend)
 
-**Using iceberg-cpp from your project:** the installed public headers require
-C++20 at minimum, so applications that link against iceberg-cpp can be
-compiled as C++20 or later. The library itself is still built as C++23.
-
 **Optional:**
 
 - Python 3 and [pre-commit](https://pre-commit.com/) (for linting)
 
+## C++20 Compatibility
+
+iceberg-cpp is built as C++23, but its installed public headers are also usable
+from C++20. Applications that consume iceberg-cpp can therefore be compiled as
+C++20 or later; C++20 is the minimum standard supported for the public headers.
+
+This contract is checked in two ways: `cpp20_compatibility_test` compiles every
+public header as C++20 as part of the regular test suite, and CI builds the
+[example](example) against the installed headers as both C++20 and C++23 (see
+`ICEBERG_EXAMPLE_CXX_STANDARD` in [Build Examples](#build-examples)). The test's
+header list, `src/iceberg/cpp20_compatibility_internal.h`, is generated by
+`ci/scripts/generate_public_headers.py`; a pre-commit hook fails whenever it is
+out of date, so new public headers cannot be missed.
+
 ## Quick Start
 
 ```bash
diff --git a/ci/scripts/generate_public_headers.py b/ci/scripts/generate_public_headers.py
new file mode 100755
index 000000000..56f196d87
--- /dev/null
+++ b/ci/scripts/generate_public_headers.py
@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Regenerate src/iceberg/cpp20_compatibility_internal.h.
+
+The generated header includes every public header, i.e. every header that
+iceberg_install_all_headers() installs: *.h files in a directory whose
+CMakeLists.txt calls it, except those with "internal" in their name. This script
+applies the same rule, so the list never has to be maintained by hand. The
+generate-public-headers pre-commit hook runs it and fails when the checked-in
+header is out of date.
+
+Headers of optional components are wrapped in a macro that
+cpp20_compatibility_test defines only when that component is built.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+SRC = ROOT / "src"
+OUTPUT = SRC / "iceberg" / "cpp20_compatibility_internal.h"
+
+# Install path prefix -> macro guarding it. The first match wins, so list more
+# specific prefixes first. Anything unmatched is always built.
+OPTIONAL_COMPONENTS = [
+    ("iceberg/catalog/hive", "ICEBERG_PUBLIC_HEADERS_HIVE"),
+    ("iceberg/catalog/rest", "ICEBERG_PUBLIC_HEADERS_REST"),
+    ("iceberg/catalog/sql", "ICEBERG_PUBLIC_HEADERS_SQL_CATALOG"),
+    ("iceberg/arrow", "ICEBERG_PUBLIC_HEADERS_BUNDLE"),
+    ("iceberg/avro", "ICEBERG_PUBLIC_HEADERS_BUNDLE"),
+    ("iceberg/parquet", "ICEBERG_PUBLIC_HEADERS_BUNDLE"),
+]
+
+INSTALL_CALL = re.compile(r"iceberg_install_all_headers\(\s*([^\s)]+)")
+
+LICENSE = """\
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+"""
+
+
+def component_of(install_path: str) -> str | None:
+    for prefix, macro in OPTIONAL_COMPONENTS:
+        if install_path == prefix or install_path.startswith(prefix + "/"):
+            return macro
+    return None
+
+
+def collect_public_headers() -> dict[str | None, list[str]]:
+    headers: dict[str | None, list[str]] = {}
+    for cmake_file in sorted(SRC.rglob("CMakeLists.txt")):
+        for install_path in INSTALL_CALL.findall(cmake_file.read_text()):
+            for header in cmake_file.parent.iterdir():
+                if header.suffix != ".h" or "internal" in header.name:
+                    continue
+                headers.setdefault(component_of(install_path), []).append(
+                    f"{install_path}/{header.name}"
+                )
+    return headers
+
+
+def render(headers: dict[str | None, list[str]]) -> str:
+    lines = [
+        LICENSE,
+        "// Generated by ci/scripts/generate_public_headers.py; do not edit by hand.",
+        "//",
+        "// Includes every public (installed) header. cpp20_compatibility_test compiles",
+        "// it as C++20 to keep the public headers usable from C++20.",
+        "",
+        "#pragma once",
+        "",
+    ]
+    lines += [f'#include "{h}"' for h in sorted(headers.get(None, []))]
+    for macro in sorted({m for _, m in OPTIONAL_COMPONENTS}):
+        if macro not in headers:
+            continue
+        lines += ["", f"#ifdef {macro}"]
+        lines += [f'#  include "{h}"' for h in sorted(headers[macro])]
+        lines += [f"#endif  // {macro}"]
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    content = render(collect_public_headers())
+    if OUTPUT.exists() and OUTPUT.read_text() == content:
+        return 0
+    OUTPUT.write_text(content)
+    print(f"Regenerated {OUTPUT.relative_to(ROOT)}; commit the updated file.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/example/CMakeLists.txt b/example/CMakeLists.txt
index 44c599cf8..5e565dfbc 100644
--- a/example/CMakeLists.txt
+++ b/example/CMakeLists.txt
@@ -21,14 +21,13 @@ cmake_minimum_required(VERSION 3.25)
 project(example)
 
 # C++20 is the minimum standard iceberg-cpp's public headers support, so the
-# example builds as C++20 by default to keep that contract exercised. Set this to
-# 23 to also check the headers from a C++23 consumer.
+# example builds as C++20 by default to keep that contract exercised. Set this to a
+# newer standard (e.g. 23) to check the headers from a newer consumer as well.
 set(ICEBERG_EXAMPLE_CXX_STANDARD
     20
-    CACHE STRING "C++ standard used to build the example (20 or 23)")
-set_property(CACHE ICEBERG_EXAMPLE_CXX_STANDARD PROPERTY STRINGS 20 23)
-if(NOT ICEBERG_EXAMPLE_CXX_STANDARD MATCHES "^(20|23)$")
-  message(FATAL_ERROR "ICEBERG_EXAMPLE_CXX_STANDARD must be 20 or 23, got "
+    CACHE STRING "C++ standard used to build the example (20 or newer)")
+if(ICEBERG_EXAMPLE_CXX_STANDARD MATCHES "^(98|11|14|17)$")
+  message(FATAL_ERROR "ICEBERG_EXAMPLE_CXX_STANDARD must be 20 or newer, got "
                       "'${ICEBERG_EXAMPLE_CXX_STANDARD}'")
 endif()
 
@@ -72,11 +71,8 @@ if(NOT ICEBERG_PUBLIC_INCLUDE_DIR)
   message(FATAL_ERROR "Could not locate iceberg's installed public headers")
 endif()
 
-file(GLOB_RECURSE
-     ICEBERG_PUBLIC_HEADERS
-     CONFIGURE_DEPENDS
-     "${ICEBERG_PUBLIC_INCLUDE_DIR}/iceberg/*.h"
-     "${ICEBERG_PUBLIC_INCLUDE_DIR}/iceberg/*.hpp")
+file(GLOB_RECURSE ICEBERG_PUBLIC_HEADERS CONFIGURE_DEPENDS
+     "${ICEBERG_PUBLIC_INCLUDE_DIR}/iceberg/*.h")
 list(SORT ICEBERG_PUBLIC_HEADERS)
 
 set(ICEBERG_PUBLIC_HEADER_CHECK_SOURCE
diff --git a/mkdocs/docs/getting-started.md b/mkdocs/docs/getting-started.md
index fea517e3a..8fa08cdc8 100644
--- a/mkdocs/docs/getting-started.md
+++ b/mkdocs/docs/getting-started.md
@@ -23,13 +23,23 @@
 
 **Required:**
 
-- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+) to build iceberg-cpp itself
+- C++23 compliant compiler (GCC 14+, Clang 18+, MSVC 2022+)
 - CMake 3.25+
 - [Ninja](https://ninja-build.org/) (recommended build backend)
 
-**Using iceberg-cpp from your project:** the installed public headers require
-C++20 at minimum, so applications that link against iceberg-cpp can be
-compiled as C++20 or later. The library itself is still built as C++23.
+## C++20 Compatibility
+
+iceberg-cpp is built as C++23, but its installed public headers are also usable
+from C++20. Applications that consume iceberg-cpp can therefore be compiled as
+C++20 or later; C++20 is the minimum standard supported for the public headers.
+
+This contract is checked in two ways: `cpp20_compatibility_test` compiles every
+public header as C++20 as part of the regular test suite, and CI builds the
+example against the installed headers as both C++20 and C++23 (see
+`ICEBERG_EXAMPLE_CXX_STANDARD` in [Build Examples](#build-examples)). The test's
+header list, `src/iceberg/cpp20_compatibility_internal.h`, is generated by
+`ci/scripts/generate_public_headers.py`; a pre-commit hook fails whenever it is
+out of date, so new public headers cannot be missed.
 
 ## Quick Start
 
diff --git a/src/iceberg/cpp20_compatibility_internal.h b/src/iceberg/cpp20_compatibility_internal.h
new file mode 100644
index 000000000..d9162b924
--- /dev/null
+++ b/src/iceberg/cpp20_compatibility_internal.h
@@ -0,0 +1,244 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Generated by ci/scripts/generate_public_headers.py; do not edit by hand.
+//
+// Includes every public (installed) header. cpp20_compatibility_test compiles
+// it as C++20 to keep the public headers usable from C++20.
+
+#pragma once
+
+#include "iceberg/arrow_c_data.h"
+#include "iceberg/catalog.h"
+#include "iceberg/catalog/catalog_util.h"
+#include "iceberg/catalog/memory/in_memory_catalog.h"
+#include "iceberg/catalog/session_catalog.h"
+#include "iceberg/catalog/session_context.h"
+#include "iceberg/constants.h"
+#include "iceberg/data/data_writer.h"
+#include "iceberg/data/delete_filter.h"
+#include "iceberg/data/delete_loader.h"
+#include "iceberg/data/equality_delete_writer.h"
+#include "iceberg/data/file_scan_task_reader.h"
+#include "iceberg/data/position_delete_writer.h"
+#include "iceberg/data/writer.h"
+#include "iceberg/delete_file_index.h"
+#include "iceberg/deletes/dv_writer.h"
+#include "iceberg/deletes/position_delete_index.h"
+#include "iceberg/deletes/position_delete_range_consumer.h"
+#include "iceberg/deletes/roaring_position_bitmap.h"
+#include "iceberg/encryption/encrypted_key.h"
+#include "iceberg/exception.h"
+#include "iceberg/expected.h"
+#include "iceberg/expression/aggregate.h"
+#include "iceberg/expression/binder.h"
+#include "iceberg/expression/evaluator.h"
+#include "iceberg/expression/expression.h"
+#include "iceberg/expression/expression_visitor.h"
+#include "iceberg/expression/expressions.h"
+#include "iceberg/expression/inclusive_metrics_evaluator.h"
+#include "iceberg/expression/literal.h"
+#include "iceberg/expression/manifest_evaluator.h"
+#include "iceberg/expression/predicate.h"
+#include "iceberg/expression/projections.h"
+#include "iceberg/expression/residual_evaluator.h"
+#include "iceberg/expression/rewrite_not.h"
+#include "iceberg/expression/sanitize_expression.h"
+#include "iceberg/expression/strict_metrics_evaluator.h"
+#include "iceberg/expression/term.h"
+#include "iceberg/file_format.h"
+#include "iceberg/file_io.h"
+#include "iceberg/file_io_registry.h"
+#include "iceberg/file_reader.h"
+#include "iceberg/file_writer.h"
+#include "iceberg/geospatial.h"
+#include "iceberg/iceberg_bundle_export.h"
+#include "iceberg/iceberg_data_export.h"
+#include "iceberg/iceberg_export.h"
+#include "iceberg/inheritable_metadata.h"
+#include "iceberg/inspect/history_table.h"
+#include "iceberg/inspect/metadata_table.h"
+#include "iceberg/inspect/snapshots_table.h"
+#include "iceberg/location_provider.h"
+#include "iceberg/logging/cerr_logger.h"
+#include "iceberg/logging/log_level.h"
+#include "iceberg/logging/log_macros.h"
+#include "iceberg/logging/logger.h"
+#include "iceberg/logging/loggers.h"
+#include "iceberg/logging/short_log_macros.h"
+#include "iceberg/manifest/manifest_entry.h"
+#include "iceberg/manifest/manifest_filter_manager.h"
+#include "iceberg/manifest/manifest_group.h"
+#include "iceberg/manifest/manifest_list.h"
+#include "iceberg/manifest/manifest_merge_manager.h"
+#include "iceberg/manifest/manifest_reader.h"
+#include "iceberg/manifest/manifest_writer.h"
+#include "iceberg/manifest/rolling_manifest_writer.h"
+#include "iceberg/metadata_columns.h"
+#include "iceberg/metrics.h"
+#include "iceberg/metrics/commit_report.h"
+#include "iceberg/metrics/counter.h"
+#include "iceberg/metrics/metrics_context.h"
+#include "iceberg/metrics/metrics_reporter.h"
+#include "iceberg/metrics/metrics_reporters.h"
+#include "iceberg/metrics/metrics_types.h"
+#include "iceberg/metrics/scan_report.h"
+#include "iceberg/metrics/timer.h"
+#include "iceberg/metrics_config.h"
+#include "iceberg/name_mapping.h"
+#include "iceberg/partition_field.h"
+#include "iceberg/partition_spec.h"
+#include "iceberg/puffin/file_metadata.h"
+#include "iceberg/puffin/puffin_format.h"
+#include "iceberg/puffin/puffin_reader.h"
+#include "iceberg/puffin/puffin_writer.h"
+#include "iceberg/puffin/type_fwd.h"
+#include "iceberg/resolving_file_io.h"
+#include "iceberg/result.h"
+#include "iceberg/row/arrow_array_wrapper.h"
+#include "iceberg/row/manifest_wrapper.h"
+#include "iceberg/row/partition_values.h"
+#include "iceberg/row/struct_like.h"
+#include "iceberg/schema.h"
+#include "iceberg/schema_field.h"
+#include "iceberg/schema_util.h"
+#include "iceberg/snapshot.h"
+#include "iceberg/sort_field.h"
+#include "iceberg/sort_order.h"
+#include "iceberg/statistics_file.h"
+#include "iceberg/storage_credential.h"
+#include "iceberg/table.h"
+#include "iceberg/table_identifier.h"
+#include "iceberg/table_metadata.h"
+#include "iceberg/table_properties.h"
+#include "iceberg/table_requirement.h"
+#include "iceberg/table_requirements.h"
+#include "iceberg/table_scan.h"
+#include "iceberg/table_update.h"
+#include "iceberg/transaction.h"
+#include "iceberg/transform.h"
+#include "iceberg/transform_function.h"
+#include "iceberg/type.h"
+#include "iceberg/type_fwd.h"
+#include "iceberg/update/delete_files.h"
+#include "iceberg/update/expire_snapshots.h"
+#include "iceberg/update/fast_append.h"
+#include "iceberg/update/merge_append.h"
+#include "iceberg/update/merging_snapshot_update.h"
+#include "iceberg/update/overwrite_files.h"
+#include "iceberg/update/pending_update.h"
+#include "iceberg/update/replace_partitions.h"
+#include "iceberg/update/rewrite_files.h"
+#include "iceberg/update/row_delta.h"
+#include "iceberg/update/set_snapshot.h"
+#include "iceberg/update/snapshot_manager.h"
+#include "iceberg/update/snapshot_update.h"
+#include "iceberg/update/update_location.h"
+#include "iceberg/update/update_partition_spec.h"
+#include "iceberg/update/update_partition_statistics.h"
+#include "iceberg/update/update_properties.h"
+#include "iceberg/update/update_schema.h"
+#include "iceberg/update/update_snapshot_reference.h"
+#include "iceberg/update/update_sort_order.h"
+#include "iceberg/update/update_statistics.h"
+#include "iceberg/util/base64.h"
+#include "iceberg/util/bucket_util.h"
+#include "iceberg/util/checked_cast.h"
+#include "iceberg/util/config.h"
+#include "iceberg/util/content_file_util.h"
+#include "iceberg/util/conversions.h"
+#include "iceberg/util/data_file_set.h"
+#include "iceberg/util/decimal.h"
+#include "iceberg/util/endian.h"
+#include "iceberg/util/error_collector.h"
+#include "iceberg/util/executor.h"
+#include "iceberg/util/formattable.h"
+#include "iceberg/util/formatter.h"
+#include "iceberg/util/functional.h"
+#include "iceberg/util/int128.h"
+#include "iceberg/util/lazy.h"
+#include "iceberg/util/location_util.h"
+#include "iceberg/util/macros.h"
+#include "iceberg/util/partition_value_util.h"
+#include "iceberg/util/property_util.h"
+#include "iceberg/util/retry_util.h"
+#include "iceberg/util/snapshot_util.h"
+#include "iceberg/util/stream.h"
+#include "iceberg/util/string_util.h"
+#include "iceberg/util/struct_like_set.h"
+#include "iceberg/util/task_group.h"
+#include "iceberg/util/temporal_util.h"
+#include "iceberg/util/timepoint.h"
+#include "iceberg/util/transform_util.h"
+#include "iceberg/util/truncate_util.h"
+#include "iceberg/util/type_util.h"
+#include "iceberg/util/unreachable.h"
+#include "iceberg/util/url_encoder.h"
+#include "iceberg/util/uuid.h"
+#include "iceberg/util/visit_type.h"
+#include "iceberg/util/visitor_generate.h"
+
+#ifdef ICEBERG_PUBLIC_HEADERS_BUNDLE
+#  include "iceberg/arrow/arrow_io_util.h"
+#  include "iceberg/arrow/arrow_register.h"
+#  include "iceberg/arrow/s3/s3_properties.h"
+#  include "iceberg/avro/avro_constants.h"
+#  include "iceberg/avro/avro_metrics.h"
+#  include "iceberg/avro/avro_reader.h"
+#  include "iceberg/avro/avro_register.h"
+#  include "iceberg/avro/avro_writer.h"
+#  include "iceberg/parquet/parquet_reader.h"
+#  include "iceberg/parquet/parquet_register.h"
+#  include "iceberg/parquet/parquet_writer.h"
+#endif  // ICEBERG_PUBLIC_HEADERS_BUNDLE
+
+#ifdef ICEBERG_PUBLIC_HEADERS_HIVE
+#  include "iceberg/catalog/hive/hive_catalog.h"
+#  include "iceberg/catalog/hive/hive_catalog_properties.h"
+#  include "iceberg/catalog/hive/hms_client.h"
+#  include "iceberg/catalog/hive/iceberg_hive_export.h"
+#endif  // ICEBERG_PUBLIC_HEADERS_HIVE
+
+#ifdef ICEBERG_PUBLIC_HEADERS_REST
+#  include "iceberg/catalog/rest/auth/auth_manager.h"
+#  include "iceberg/catalog/rest/auth/auth_managers.h"
+#  include "iceberg/catalog/rest/auth/auth_properties.h"
+#  include "iceberg/catalog/rest/auth/auth_session.h"
+#  include "iceberg/catalog/rest/auth/oauth2_util.h"
+#  include "iceberg/catalog/rest/auth/token_refresh_scheduler.h"
+#  include "iceberg/catalog/rest/catalog_properties.h"
+#  include "iceberg/catalog/rest/constant.h"
+#  include "iceberg/catalog/rest/endpoint.h"
+#  include "iceberg/catalog/rest/error_handlers.h"
+#  include "iceberg/catalog/rest/http_client.h"
+#  include "iceberg/catalog/rest/http_request.h"
+#  include "iceberg/catalog/rest/iceberg_rest_export.h"
+#  include "iceberg/catalog/rest/resource_paths.h"
+#  include "iceberg/catalog/rest/rest_catalog.h"
+#  include "iceberg/catalog/rest/rest_file_io.h"
+#  include "iceberg/catalog/rest/rest_util.h"
+#  include "iceberg/catalog/rest/type_fwd.h"
+#  include "iceberg/catalog/rest/types.h"
+#endif  // ICEBERG_PUBLIC_HEADERS_REST
+
+#ifdef ICEBERG_PUBLIC_HEADERS_SQL_CATALOG
+#  include "iceberg/catalog/sql/catalog_store.h"
+#  include "iceberg/catalog/sql/iceberg_sql_catalog_export.h"
+#  include "iceberg/catalog/sql/sql_catalog.h"
+#endif  // ICEBERG_PUBLIC_HEADERS_SQL_CATALOG
diff --git a/src/iceberg/test/CMakeLists.txt b/src/iceberg/test/CMakeLists.txt
index a8e036164..b0ed4e957 100644
--- a/src/iceberg/test/CMakeLists.txt
+++ b/src/iceberg/test/CMakeLists.txt
@@ -364,3 +364,55 @@ if(ICEBERG_BUILD_HIVE)
 
   add_hive_iceberg_test(hive_catalog_test SOURCES hms_client_test.cc)
 endif()
+
+# Compile every public header as C++20. The library itself builds as C++23, but its
+# public headers must stay usable from C++20. The header list lives in
+# iceberg/cpp20_compatibility_internal.h, generated by
+# ci/scripts/generate_public_headers.py; headers of optional components are enabled
+# with the matching ICEBERG_PUBLIC_HEADERS_* macro.
+add_executable(cpp20_compatibility_test cpp20_compatibility_test.cc)
+set_target_properties(cpp20_compatibility_test
+                      PROPERTIES CXX_STANDARD 20 CXX_STANDARD_REQUIRED ON CXX_EXTENSIONS
+                                                                          OFF)
+target_link_libraries(cpp20_compatibility_test
+                      PRIVATE "$<IF:$<TARGET_EXISTS:iceberg_static>,iceberg_static,iceberg_shared>"
+                              "$<IF:$<TARGET_EXISTS:iceberg_data_static>,iceberg_data_static,iceberg_data_shared>"
+)
+if(ICEBERG_BUILD_BUNDLE)
+  target_link_libraries(cpp20_compatibility_test
+                        PRIVATE "$<IF:$<TARGET_EXISTS:iceberg_bundle_static>,iceberg_bundle_static,iceberg_bundle_shared>"
+  )
+  target_compile_definitions(cpp20_compatibility_test
+                             PRIVATE ICEBERG_PUBLIC_HEADERS_BUNDLE)
+endif()
+if(ICEBERG_BUILD_REST)
+  target_link_libraries(cpp20_compatibility_test
+                        PRIVATE "$<IF:$<TARGET_EXISTS:iceberg_rest_static>,iceberg_rest_static,iceberg_rest_shared>"
+  )
+  target_compile_definitions(cpp20_compatibility_test PRIVATE ICEBERG_PUBLIC_HEADERS_REST)
+endif()
+# The Hive and SQL catalog libraries are not linked: their build-time dependencies
+# (e.g. sqlpp23) require C++23 and would propagate cxx_std_23 to this target. Their
+# public headers only need the libraries' include directories and compile
+# definitions, so take just those.
+foreach(ICEBERG_HEADER_ONLY_COMPONENT IN ITEMS hive sql_catalog)
+  string(TOUPPER "${ICEBERG_HEADER_ONLY_COMPONENT}" ICEBERG_HEADER_ONLY_COMPONENT_UPPER)
+  if(NOT ICEBERG_BUILD_${ICEBERG_HEADER_ONLY_COMPONENT_UPPER})
+    continue()
+  endif()
+  set(ICEBERG_HEADER_ONLY_TARGET
+      "$<IF:$<TARGET_EXISTS:iceberg_${ICEBERG_HEADER_ONLY_COMPONENT}_static>,iceberg_${ICEBERG_HEADER_ONLY_COMPONENT}_static,iceberg_${ICEBERG_HEADER_ONLY_COMPONENT}_shared>"
+  )
+  target_include_directories(cpp20_compatibility_test
+                             PRIVATE "$<TARGET_PROPERTY:${ICEBERG_HEADER_ONLY_TARGET},INTERFACE_INCLUDE_DIRECTORIES>"
+  )
+  target_compile_definitions(cpp20_compatibility_test
+                             PRIVATE "$<TARGET_PROPERTY:${ICEBERG_HEADER_ONLY_TARGET},INTERFACE_COMPILE_DEFINITIONS>"
+                                     ICEBERG_PUBLIC_HEADERS_${ICEBERG_HEADER_ONLY_COMPONENT_UPPER}
+  )
+endforeach()
+if(MSVC_TOOLCHAIN)
+  # /Zc:preprocessor: conforming preprocessor for the __VA_OPT__ in the logging macros.
+  target_compile_options(cpp20_compatibility_test PRIVATE /bigobj /Zc:preprocessor)
+endif()
+add_test(NAME cpp20_compatibility_test COMMAND cpp20_compatibility_test)
diff --git a/src/iceberg/test/cpp20_compatibility_test.cc b/src/iceberg/test/cpp20_compatibility_test.cc
new file mode 100644
index 000000000..29410de9d
--- /dev/null
+++ b/src/iceberg/test/cpp20_compatibility_test.cc
@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Compiles every public header as C++20, the minimum standard supported for them.
+// The header list is generated by ci/scripts/generate_public_headers.py and kept
+// up to date by the generate-public-headers pre-commit hook.
+
+#include "iceberg/cpp20_compatibility_internal.h"
+
+#if defined(_MSVC_LANG)
+static_assert(_MSVC_LANG == 202002L, "cpp20_compatibility_test must build as C++20");
+#else
+static_assert(__cplusplus == 202002L, "cpp20_compatibility_test must build as C++20");
+#endif
+
+int main() { return 0; }

From 31e9943caeeba1db600de00db5e86751c9340681 Mon Sep 17 00:00:00 2001
From: Ping Liu <ping.liu.ping@gmail.com>
Date: Mon, 28 Sep 2026 13:59:56 +0800
Subject: [PATCH 14/14] keep a single API shape for ErrorCollector and
 SnapshotUpdate

---
 src/iceberg/update/snapshot_update.h        | 123 +++-----------------
 src/iceberg/update/update_partition_spec.cc |  10 +-
 src/iceberg/update/update_sort_order.cc     |   5 +-
 src/iceberg/util/error_collector.h          |  59 ++--------
 4 files changed, 32 insertions(+), 165 deletions(-)

diff --git a/src/iceberg/update/snapshot_update.h b/src/iceberg/update/snapshot_update.h
index c3b33b8de..381b4d00b 100644
--- a/src/iceberg/update/snapshot_update.h
+++ b/src/iceberg/update/snapshot_update.h
@@ -62,112 +62,10 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
   bool IsRetryable() const override { return true; }
   Status Commit() override;
 
-// C++23 uses deducing `this` so chaining keeps returning the derived update type.
-// C++20 exposes the same operations but returns SnapshotUpdate&, because preserving
-// the derived type would require making the update hierarchy CRTP. Keyed on the
-// language version rather than __cpp_explicit_this_parameter, which Apple clang does
-// not define, and compared with "> 202002L" because MSVC's /std:c++latest only
-// promises a value above 202002L.
-#if __cplusplus > 202002L || (defined(_MSVC_LANG) && _MSVC_LANG > 202002L)
   /// \brief Set the metrics reporter for this snapshot update.
   ///
   /// \param reporter The metrics reporter to use.
   /// \return Reference to this for method chaining.
-  auto& ReportWith(this auto& self, std::shared_ptr<MetricsReporter> reporter) {
-    static_cast<SnapshotUpdate&>(self).reporter_ = std::move(reporter);
-    return self;
-  }
-
-  /// \brief Set a callback to delete files instead of the table's default.
-  ///
-  /// \param delete_func A function used to delete file locations.
-  /// \return This update for method chaining.
-  /// \note Cannot be called more than once.
-  auto& DeleteWith(this auto& self,
-                   std::function<Status(const std::string&)> delete_func) {
-    if (self.delete_func_) {
-      return self.AddError(ErrorKind::kInvalidArgument,
-                           "Cannot set delete callback more than once");
-    }
-    self.delete_func_ = std::move(delete_func);
-    return self;
-  }
-
-  /// \brief Stage a snapshot in table metadata, but do not make it current.
-  ///
-  /// The snapshot is assigned an ID and added to table metadata. The table's
-  /// current snapshot ID is not updated.
-  ///
-  /// \return This update for method chaining.
-  auto& StageOnly(this auto& self) {
-    self.stage_only_ = true;
-    return self;
-  }
-
-  /// \brief Configure an executor for manifest planning work.
-  ///
-  /// \param executor Executor to use while planning manifests.
-  /// \return Reference to this for method chaining.
-  auto& ScanManifestsWith(this auto& self, Executor& executor) {
-    self.plan_executor_ = std::ref(executor);
-    return self;
-  }
-
-  /// \brief Perform operations on a particular branch.
-  ///
-  /// \param branch The name of a SnapshotRef of type branch.
-  /// \return This update for method chaining.
-  auto& ToBranch(this auto& self, const std::string& branch) {
-    if (branch.empty()) [[unlikely]] {
-      return self.AddError(ErrorKind::kInvalidArgument, "Branch name cannot be empty");
-    }
-
-    if (auto ref_it = self.base().refs.find(branch); ref_it != self.base().refs.end()) {
-      if (ref_it->second->type() != SnapshotRefType::kBranch) {
-        return self.AddError(ErrorKind::kInvalidArgument,
-                             "{} is a tag, not a branch. Tags cannot be targets for "
-                             "producing snapshots",
-                             branch);
-      }
-    }
-
-    self.target_branch_ = branch;
-    return self;
-  }
-
-  /// \brief Set a summary property in the snapshot produced by this update.
-  ///
-  /// \param property A String property name.
-  /// \param value A String property value.
-  /// \return This update for method chaining.
-  auto& Set(this auto& self, const std::string& property, const std::string& value) {
-    static_cast<SnapshotUpdate&>(self).SetSummaryProperty(property, value);
-    return self;
-  }
-
-  /// \brief Configure an executor and max writer count for writing new manifests.
-  ///
-  /// If this method is not called, manifest writes remain serial. When configured,
-  /// files may be split into independent rolling-writer groups.
-  ///
-  /// \note Custom FileIO implementations and registered writer factories used for
-  /// manifest writes must support concurrent calls when an executor is configured.
-  auto& WriteManifestsWith(this auto& self, Executor& executor, int32_t parallelism) {
-    if (parallelism <= 0) [[unlikely]] {
-      return self.AddError(
-          ErrorKind::kInvalidArgument,
-          "Manifest write parallelism must be greater than 0, but was: {}", parallelism);
-    }
-
-    self.write_manifest_executor_ = std::ref(executor);
-    self.write_manifest_parallelism_ = parallelism;
-    return self;
-  }
-#else
-  /// \brief Set the metrics reporter for this snapshot update.
-  ///
-  /// \param reporter The metrics reporter to use.
-  /// \return This snapshot update for method chaining.
   SnapshotUpdate& ReportWith(std::shared_ptr<MetricsReporter> reporter) {
     reporter_ = std::move(reporter);
     return *this;
@@ -176,7 +74,7 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
   /// \brief Set a callback to delete files instead of the table's default.
   ///
   /// \param delete_func A function used to delete file locations.
-  /// \return This snapshot update for method chaining.
+  /// \return This update for method chaining.
   /// \note Cannot be called more than once.
   SnapshotUpdate& DeleteWith(std::function<Status(const std::string&)> delete_func) {
     if (delete_func_) {
@@ -189,7 +87,10 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
 
   /// \brief Stage a snapshot in table metadata, but do not make it current.
   ///
-  /// \return This snapshot update for method chaining.
+  /// The snapshot is assigned an ID and added to table metadata. The table's
+  /// current snapshot ID is not updated.
+  ///
+  /// \return This update for method chaining.
   SnapshotUpdate& StageOnly() {
     stage_only_ = true;
     return *this;
@@ -198,7 +99,7 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
   /// \brief Configure an executor for manifest planning work.
   ///
   /// \param executor Executor to use while planning manifests.
-  /// \return This snapshot update for method chaining.
+  /// \return Reference to this for method chaining.
   SnapshotUpdate& ScanManifestsWith(Executor& executor) {
     plan_executor_ = std::ref(executor);
     return *this;
@@ -207,7 +108,7 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
   /// \brief Perform operations on a particular branch.
   ///
   /// \param branch The name of a SnapshotRef of type branch.
-  /// \return This snapshot update for method chaining.
+  /// \return This update for method chaining.
   SnapshotUpdate& ToBranch(const std::string& branch) {
     if (branch.empty()) [[unlikely]] {
       AddError(ErrorKind::kInvalidArgument, "Branch name cannot be empty");
@@ -232,7 +133,7 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
   ///
   /// \param property A String property name.
   /// \param value A String property value.
-  /// \return This snapshot update for method chaining.
+  /// \return This update for method chaining.
   SnapshotUpdate& Set(const std::string& property, const std::string& value) {
     SetSummaryProperty(property, value);
     return *this;
@@ -240,9 +141,14 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
 
   /// \brief Configure an executor and max writer count for writing new manifests.
   ///
+  /// If this method is not called, manifest writes remain serial. When configured,
+  /// files may be split into independent rolling-writer groups.
+  ///
   /// \param executor Executor to use while writing manifests.
   /// \param parallelism Maximum number of concurrent manifest writers.
-  /// \return This snapshot update for method chaining.
+  /// \return This update for method chaining.
+  /// \note Custom FileIO implementations and registered writer factories used for
+  /// manifest writes must support concurrent calls when an executor is configured.
   SnapshotUpdate& WriteManifestsWith(Executor& executor, int32_t parallelism) {
     if (parallelism <= 0) [[unlikely]] {
       AddError(ErrorKind::kInvalidArgument,
@@ -255,7 +161,6 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdate {
     write_manifest_parallelism_ = parallelism;
     return *this;
   }
-#endif  // C++23
 
  protected:
   friend class Transaction;
diff --git a/src/iceberg/update/update_partition_spec.cc b/src/iceberg/update/update_partition_spec.cc
index 2be6a59a5..129a983b1 100644
--- a/src/iceberg/update/update_partition_spec.cc
+++ b/src/iceberg/update/update_partition_spec.cc
@@ -123,8 +123,8 @@ UpdatePartitionSpec& UpdatePartitionSpec::AddField(const std::shared_ptr<Term>&
     return AddFieldInternal(part_name, source_id, bound_transform->transform());
   }
 
-  return AddError(
-      InvalidArgument("Cannot add {} term to partition spec", term->ToString()));
+  AddError(InvalidArgument("Cannot add {} term to partition spec", term->ToString()));
+  return *this;
 }
 
 UpdatePartitionSpec& UpdatePartitionSpec::AddFieldInternal(
@@ -195,8 +195,9 @@ UpdatePartitionSpec& UpdatePartitionSpec::AddFieldInternal(
         // Rename the old deleted field
         RenameField(existing_field->name(), std::move(renamed));
       } else {
-        return AddError(
+        AddError(
             InvalidArgument("Cannot add duplicate partition field name: {}", field_name));
+        return *this;
       }
     } else {
       // Field is being deleted, rename it to avoid conflict
@@ -257,8 +258,9 @@ UpdatePartitionSpec& UpdatePartitionSpec::RemoveField(const std::shared_ptr<Term
     return RemoveFieldByTransform(key, term->ToString());
   }
 
-  return AddError(
+  AddError(
       InvalidArgument("Cannot remove {} term from partition spec", term->ToString()));
+  return *this;
 }
 
 UpdatePartitionSpec& UpdatePartitionSpec::RemoveFieldByTransform(
diff --git a/src/iceberg/update/update_sort_order.cc b/src/iceberg/update/update_sort_order.cc
index 8086b903f..36cd70b5f 100644
--- a/src/iceberg/update/update_sort_order.cc
+++ b/src/iceberg/update/update_sort_order.cc
@@ -65,8 +65,9 @@ UpdateSortOrder& UpdateSortOrder::AddSortField(const std::shared_ptr<Term>& term
     sort_fields_.emplace_back(bound_term->reference()->field_id(),
                               unbound_transform->transform(), direction, null_order);
   } else {
-    return AddError(ErrorKind::kNotSupported, "Not supported unbound term: {}",
-                    static_cast<int>(term->kind()));
+    AddError(ErrorKind::kNotSupported, "Not supported unbound term: {}",
+             static_cast<int>(term->kind()));
+    return *this;
   }
 
   return *this;
diff --git a/src/iceberg/util/error_collector.h b/src/iceberg/util/error_collector.h
index 85f652cbc..cec78e43d 100644
--- a/src/iceberg/util/error_collector.h
+++ b/src/iceberg/util/error_collector.h
@@ -104,55 +104,6 @@ class ICEBERG_EXPORT ErrorCollector {
   ErrorCollector(const ErrorCollector&) = default;
   ErrorCollector& operator=(const ErrorCollector&) = default;
 
-// C++23 uses deducing `this` so that `return AddError(...)` keeps returning the
-// derived builder type. C++20 exposes the same overloads returning ErrorCollector&,
-// because preserving the derived type would require making the builders CRTP. Keyed
-// on the language version rather than __cpp_explicit_this_parameter, which Apple
-// clang does not define, and compared with "> 202002L" because MSVC's
-// /std:c++latest only promises a value above 202002L.
-#if __cplusplus > 202002L || (defined(_MSVC_LANG) && _MSVC_LANG > 202002L)
-  /// \brief Add a specific error and return reference to derived class
-  ///
-  /// \param self Deduced reference to the derived class instance
-  /// \param kind The kind of error
-  /// \param fmt The format string
-  /// \param args The arguments to format the message
-  /// \return Reference to the derived class for method chaining
-  template <typename... Args>
-  auto& AddError(this auto& self, ErrorKind kind, const std::format_string<Args...> fmt,
-                 Args&&... args) {
-    self.errors_.emplace_back(kind, std::format(fmt, std::forward<Args>(args)...));
-    return self;
-  }
-
-  /// \brief Add an existing error object and return reference to derived class
-  ///
-  /// Useful when propagating errors from other components or reusing
-  /// error objects without deconstructing and reconstructing them.
-  ///
-  /// \param self Deduced reference to the derived class instance
-  /// \param err The error to add
-  /// \return Reference to the derived class for method chaining
-  auto& AddError(this auto& self, Error err) {
-    self.errors_.push_back(std::move(err));
-    return self;
-  }
-
-  /// \brief Add an unexpected result's error and return reference to derived class
-  ///
-  /// Useful for cases like below:
-  /// \code
-  ///   return AddError(InvalidArgument("Invalid value: {}", value));
-  /// \endcode
-  ///
-  /// \param self Deduced reference to the derived class instance
-  /// \param err The unexpected result containing the error to add
-  /// \return Reference to the derived class for method chaining
-  auto& AddError(this auto& self, unexpected<Error> err) {
-    self.errors_.push_back(std::move(err.error()));
-    return self;
-  }
-#else
   /// \brief Add a specific error
   ///
   /// \param kind The kind of error
@@ -168,6 +119,9 @@ class ICEBERG_EXPORT ErrorCollector {
 
   /// \brief Add an existing error object
   ///
+  /// Useful when propagating errors from other components or reusing
+  /// error objects without deconstructing and reconstructing them.
+  ///
   /// \param err The error to add
   /// \return This error collector for method chaining
   ErrorCollector& AddError(Error err) {
@@ -177,13 +131,18 @@ class ICEBERG_EXPORT ErrorCollector {
 
   /// \brief Add an unexpected result's error
   ///
+  /// Useful for cases like below:
+  /// \code
+  ///   AddError(InvalidArgument("Invalid value: {}", value));
+  ///   return *this;
+  /// \endcode
+  ///
   /// \param err The unexpected result containing the error to add
   /// \return This error collector for method chaining
   ErrorCollector& AddError(unexpected<Error> err) {
     errors_.push_back(std::move(err.error()));
     return *this;
   }
-#endif  // C++23
 
   /// \brief Check if any errors have been collected
   ///