From c82e13d42eb034daf48ded93b10b2aa31d89c534 Mon Sep 17 00:00:00 2001
From: FrozenlemonTee <1115306170@qq.com>
Date: Sun, 15 Mar 2026 23:12:47 +0800
Subject: [PATCH 1/7] chore: Set version 0.1.0

---
 CMakeLists.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index f1cd713..d7ab2b1 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -6,7 +6,7 @@ set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 
-project(mcpplibs-primitives VERSION 1.0.0 LANGUAGES CXX)
+project(mcpplibs-primitives VERSION 0.1.0 LANGUAGES CXX)
 
 find_package(Threads REQUIRED)
 

From 272bfc610ac6f01962fe05fab133a7af6a984c8e Mon Sep 17 00:00:00 2001
From: FrozenlemonTee <1115306170@qq.com>
Date: Sun, 15 Mar 2026 23:13:49 +0800
Subject: [PATCH 2/7] feat: Add new submodule operations

---
 src/operations/impl.cppm       | 516 +++++++++++++++++++++++++++++++++
 src/operations/operations.cppm |   6 +
 src/operations/traits.cppm     | 168 +++++++++++
 src/primitives.cppm            |   3 +-
 4 files changed, 692 insertions(+), 1 deletion(-)
 create mode 100644 src/operations/impl.cppm
 create mode 100644 src/operations/operations.cppm
 create mode 100644 src/operations/traits.cppm

diff --git a/src/operations/impl.cppm b/src/operations/impl.cppm
new file mode 100644
index 0000000..dc53e31
--- /dev/null
+++ b/src/operations/impl.cppm
@@ -0,0 +1,516 @@
+module;
+#include <atomic>
+#include <concepts>
+#include <exception>
+#include <limits>
+#include <type_traits>
+
+export module mcpplibs.primitives.operations.impl;
+
+import mcpplibs.primitives.operations.traits;
+import mcpplibs.primitives.policy;
+import mcpplibs.primitives.primitive;
+import mcpplibs.primitives.underlying;
+
+export namespace mcpplibs::primitives::operations {
+
+namespace details {
+
+template <typename T>
+constexpr bool add_overflow(T lhs, T rhs) noexcept {
+  if constexpr (!std::is_integral_v<T>) {
+    return false;
+  } else if constexpr (std::is_signed_v<T>) {
+    using limits = std::numeric_limits<T>;
+    return (rhs > 0 && lhs > limits::max() - rhs) ||
+           (rhs < 0 && lhs < limits::min() - rhs);
+  } else {
+    using limits = std::numeric_limits<T>;
+    return lhs > limits::max() - rhs;
+  }
+}
+
+template <typename T>
+constexpr bool sub_overflow(T lhs, T rhs) noexcept {
+  if constexpr (!std::is_integral_v<T>) {
+    return false;
+  } else if constexpr (std::is_signed_v<T>) {
+    using limits = std::numeric_limits<T>;
+    return (rhs < 0 && lhs > limits::max() + rhs * static_cast<T>(-1)) ||
+           (rhs > 0 && lhs < limits::min() + rhs);
+  } else {
+    return lhs < rhs;
+  }
+}
+
+template <typename T>
+constexpr bool mul_overflow(T lhs, T rhs) noexcept {
+  if constexpr (!std::is_integral_v<T>) {
+    return false;
+  } else if (lhs == 0 || rhs == 0) {
+    return false;
+  } else if constexpr (std::is_signed_v<T>) {
+    using limits = std::numeric_limits<T>;
+    if (lhs == -1) {
+      return rhs == limits::min();
+    }
+    if (rhs == -1) {
+      return lhs == limits::min();
+    }
+    if (lhs > 0) {
+      return (rhs > 0) ? lhs > limits::max() / rhs
+                       : rhs < limits::min() / lhs;
+    }
+    return (rhs > 0) ? lhs < limits::min() / rhs
+                     : lhs != 0 && rhs < limits::max() / lhs;
+  } else {
+    using limits = std::numeric_limits<T>;
+    return lhs > limits::max() / rhs;
+  }
+}
+
+template <typename T>
+constexpr T saturating_add(T lhs, T rhs) noexcept {
+  if constexpr (!std::is_integral_v<T>) {
+    return static_cast<T>(lhs + rhs);
+  } else {
+    using limits = std::numeric_limits<T>;
+    if (!add_overflow(lhs, rhs)) {
+      return static_cast<T>(lhs + rhs);
+    }
+    if constexpr (std::is_signed_v<T>) {
+      return rhs >= 0 ? limits::max() : limits::min();
+    } else {
+      return limits::max();
+    }
+  }
+}
+
+template <typename T>
+constexpr T saturating_sub(T lhs, T rhs) noexcept {
+  if constexpr (!std::is_integral_v<T>) {
+    return static_cast<T>(lhs - rhs);
+  } else {
+    using limits = std::numeric_limits<T>;
+    if (!sub_overflow(lhs, rhs)) {
+      return static_cast<T>(lhs - rhs);
+    }
+    if constexpr (std::is_signed_v<T>) {
+      return rhs > 0 ? limits::min() : limits::max();
+    } else {
+      return limits::min();
+    }
+  }
+}
+
+template <typename T>
+constexpr T saturating_mul(T lhs, T rhs) noexcept {
+  if constexpr (!std::is_integral_v<T>) {
+    return static_cast<T>(lhs * rhs);
+  } else {
+    using limits = std::numeric_limits<T>;
+    if (!mul_overflow(lhs, rhs)) {
+      return static_cast<T>(lhs * rhs);
+    }
+    if constexpr (std::is_signed_v<T>) {
+      return ((lhs < 0) ^ (rhs < 0)) ? limits::min() : limits::max();
+    } else {
+      return limits::max();
+    }
+  }
+}
+
+} // namespace details
+
+// ===== Built-in value policy behaviors =====
+
+template <typename OpTag>
+struct value_policy_behavior<policy::checked_value, OpTag> {
+  template <typename T>
+  static constexpr T add(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs + rhs);
+  }
+
+  template <typename T>
+  static constexpr T sub(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs - rhs);
+  }
+
+  template <typename T>
+  static constexpr T mul(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs * rhs);
+  }
+};
+
+template <typename OpTag>
+struct value_policy_behavior<policy::unchecked_value, OpTag> {
+  template <typename T>
+  static constexpr T add(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs + rhs);
+  }
+
+  template <typename T>
+  static constexpr T sub(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs - rhs);
+  }
+
+  template <typename T>
+  static constexpr T mul(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs * rhs);
+  }
+};
+
+template <typename OpTag>
+struct value_policy_behavior<policy::saturating_value, OpTag> {
+  template <typename T>
+  static constexpr T add(T lhs, T rhs) noexcept {
+    return details::saturating_add(lhs, rhs);
+  }
+
+  template <typename T>
+  static constexpr T sub(T lhs, T rhs) noexcept {
+    return details::saturating_sub(lhs, rhs);
+  }
+
+  template <typename T>
+  static constexpr T mul(T lhs, T rhs) noexcept {
+    return details::saturating_mul(lhs, rhs);
+  }
+};
+
+// ===== Built-in type policy behaviors =====
+
+template <typename OpTag>
+struct type_policy_behavior<policy::strict_type, OpTag> {
+  template <typename L, typename R>
+  using result_type = std::remove_cv_t<L>;
+
+  template <typename Out, typename In>
+  static constexpr Out cast_lhs(In const &value) noexcept {
+    return static_cast<Out>(value);
+  }
+
+  template <typename Out, typename In>
+  static constexpr Out cast_rhs(In const &value) noexcept {
+    static_assert(std::same_as<std::remove_cv_t<Out>, std::remove_cv_t<In>>,
+                  "strict_type requires both operands to have same type");
+    return static_cast<Out>(value);
+  }
+};
+
+template <typename OpTag>
+struct type_policy_behavior<policy::category_compatible_type, OpTag> {
+  template <typename L, typename R>
+  using result_type = std::common_type_t<L, R>;
+
+  template <typename Out, typename In>
+  static constexpr Out cast_lhs(In const &value) noexcept {
+    return static_cast<Out>(value);
+  }
+
+  template <typename Out, typename In>
+  static constexpr Out cast_rhs(In const &value) noexcept {
+    static_assert(
+        underlying::traits<std::remove_cv_t<Out>>::kind ==
+            underlying::traits<std::remove_cv_t<In>>::kind,
+        "category_compatible_type requires same underlying category");
+    return static_cast<Out>(value);
+  }
+};
+
+template <typename OpTag>
+struct type_policy_behavior<policy::transparent_type, OpTag> {
+  template <typename L, typename R>
+  using result_type = std::common_type_t<L, R>;
+
+  template <typename Out, typename In>
+  static constexpr Out cast_lhs(In const &value) noexcept {
+    return static_cast<Out>(value);
+  }
+
+  template <typename Out, typename In>
+  static constexpr Out cast_rhs(In const &value) noexcept {
+    return static_cast<Out>(value);
+  }
+};
+
+// ===== Built-in error policy behaviors =====
+
+template <typename OpTag>
+struct error_policy_behavior<policy::throw_error, OpTag> {
+  template <typename Result, typename Fn>
+  static constexpr Result evaluate(Fn &&fn) noexcept(noexcept(fn())) {
+    return static_cast<Result>(fn());
+  }
+};
+
+template <typename OpTag>
+struct error_policy_behavior<policy::expected_error, OpTag> {
+  template <typename Result, typename Fn>
+  static constexpr Result evaluate(Fn &&fn) noexcept(noexcept(fn())) {
+    return static_cast<Result>(fn());
+  }
+};
+
+template <typename OpTag>
+struct error_policy_behavior<policy::terminate_error, OpTag> {
+  template <typename Result, typename Fn>
+  static Result evaluate(Fn &&fn) noexcept {
+    if constexpr (noexcept(fn())) {
+      return static_cast<Result>(fn());
+    } else {
+      try {
+        return static_cast<Result>(fn());
+      } catch (...) {
+        std::terminate();
+      }
+    }
+  }
+};
+
+// ===== Built-in concurrency policy behaviors =====
+
+template <typename OpTag>
+struct concurrency_policy_behavior<policy::single_thread, OpTag> {
+  template <typename Fn>
+  static constexpr auto execute(Fn &&fn) noexcept(noexcept(fn()))
+      -> decltype(fn()) {
+    return fn();
+  }
+};
+
+template <typename OpTag>
+struct concurrency_policy_behavior<policy::atomic, OpTag> {
+  template <typename Fn>
+  static auto execute(Fn &&fn) noexcept(noexcept(fn())) -> decltype(fn()) {
+    std::atomic_signal_fence(std::memory_order_seq_cst);
+    auto result = fn();
+    std::atomic_signal_fence(std::memory_order_seq_cst);
+    return result;
+  }
+};
+
+// default underlying operations
+
+template <underlying_type L, underlying_type R, policy::policy_type... Policies>
+struct traits<add_tag, L, R, Policies...> {
+  static constexpr bool enabled = true;
+  static constexpr bool noexcept_invocable = true;
+
+  using value_policy = resolved_value_policy_t<Policies...>;
+  using type_policy = resolved_type_policy_t<Policies...>;
+  using error_policy = resolved_error_policy_t<Policies...>;
+  using concurrency_policy = resolved_concurrency_policy_t<Policies...>;
+
+  using result_type =
+    type_policy_behavior<type_policy, add_tag>::template result_type<L, R>;
+
+  static constexpr result_type invoke(L const &lhs, R const &rhs) noexcept {
+    return concurrency_policy_behavior<concurrency_policy, add_tag>::execute(
+        [&]() constexpr noexcept {
+          return error_policy_behavior<error_policy, add_tag>::template evaluate<
+              result_type>([&]() constexpr noexcept {
+            return value_policy_behavior<value_policy, add_tag>::template add<result_type>(
+                type_policy_behavior<type_policy, add_tag>::template cast_lhs<result_type>(
+                    lhs),
+                type_policy_behavior<type_policy, add_tag>::template cast_rhs<result_type>(
+                    rhs));
+          });
+        });
+  }
+};
+
+template <underlying_type L, underlying_type R, policy::policy_type... Policies>
+struct traits<sub_tag, L, R, Policies...> {
+  static constexpr bool enabled = true;
+  static constexpr bool noexcept_invocable = true;
+
+  using value_policy = resolved_value_policy_t<Policies...>;
+  using type_policy = resolved_type_policy_t<Policies...>;
+  using error_policy = resolved_error_policy_t<Policies...>;
+  using concurrency_policy = resolved_concurrency_policy_t<Policies...>;
+
+  using result_type =
+    type_policy_behavior<type_policy, sub_tag>::template result_type<L, R>;
+
+  static constexpr result_type invoke(L const &lhs, R const &rhs) noexcept {
+    return concurrency_policy_behavior<concurrency_policy, sub_tag>::execute(
+        [&]() constexpr noexcept {
+          return error_policy_behavior<error_policy, sub_tag>::template evaluate<
+              result_type>([&]() constexpr noexcept {
+            return value_policy_behavior<value_policy, sub_tag>::template sub<result_type>(
+                type_policy_behavior<type_policy, sub_tag>::template cast_lhs<result_type>(
+                    lhs),
+                type_policy_behavior<type_policy, sub_tag>::template cast_rhs<result_type>(
+                    rhs));
+          });
+        });
+  }
+};
+
+template <underlying_type L, underlying_type R, policy::policy_type... Policies>
+struct traits<mul_tag, L, R, Policies...> {
+  static constexpr bool enabled = true;
+  static constexpr bool noexcept_invocable = true;
+
+  using value_policy = resolved_value_policy_t<Policies...>;
+  using type_policy = resolved_type_policy_t<Policies...>;
+  using error_policy = resolved_error_policy_t<Policies...>;
+  using concurrency_policy = resolved_concurrency_policy_t<Policies...>;
+
+  using result_type =
+    type_policy_behavior<type_policy, mul_tag>::template result_type<L, R>;
+
+  static constexpr result_type invoke(L const &lhs, R const &rhs) noexcept {
+    return concurrency_policy_behavior<concurrency_policy, mul_tag>::execute(
+        [&]() constexpr noexcept {
+          return error_policy_behavior<error_policy, mul_tag>::template evaluate<
+              result_type>([&]() constexpr noexcept {
+            return value_policy_behavior<value_policy, mul_tag>::template mul<result_type>(
+                type_policy_behavior<type_policy, mul_tag>::template cast_lhs<result_type>(
+                    lhs),
+                type_policy_behavior<type_policy, mul_tag>::template cast_rhs<result_type>(
+                    rhs));
+          });
+        });
+  }
+};
+
+// primitive operations (keep lhs policy set by default)
+template <underlying_type L, policy::policy_type... LPs, underlying_type R,
+          policy::policy_type... RPs, policy::policy_type... Policies>
+struct traits<add_tag, primitive<L, LPs...>, primitive<R, RPs...>, Policies...> {
+  static constexpr bool enabled = true;
+  static constexpr bool noexcept_invocable = true;
+
+  using value_policy = resolved_value_policy_t<LPs..., Policies...>;
+  using type_policy = resolved_type_policy_t<LPs..., Policies...>;
+  using error_policy = resolved_error_policy_t<LPs..., Policies...>;
+  using concurrency_policy = resolved_concurrency_policy_t<LPs..., Policies...>;
+
+  using rep_type =
+      type_policy_behavior<type_policy, add_tag>::template result_type<L, R>;
+  using result_type = primitive<rep_type, LPs...>;
+
+  static constexpr result_type invoke(primitive<L, LPs...> const &lhs,
+                                      primitive<R, RPs...> const &rhs) noexcept {
+    return result_type{concurrency_policy_behavior<concurrency_policy, add_tag>::execute(
+        [&]() constexpr noexcept {
+          return error_policy_behavior<error_policy, add_tag>::template evaluate<rep_type>(
+              [&]() constexpr noexcept {
+                return value_policy_behavior<value_policy, add_tag>::template add<rep_type>(
+                    type_policy_behavior<type_policy, add_tag>::template cast_lhs<rep_type>(
+                        lhs.value()),
+                    type_policy_behavior<type_policy, add_tag>::template cast_rhs<rep_type>(
+                        rhs.value()));
+              });
+        })};
+  }
+};
+
+template <underlying_type L, policy::policy_type... LPs, underlying_type R,
+          policy::policy_type... RPs, policy::policy_type... Policies>
+struct traits<sub_tag, primitive<L, LPs...>, primitive<R, RPs...>, Policies...> {
+  static constexpr bool enabled = true;
+  static constexpr bool noexcept_invocable = true;
+
+  using value_policy = resolved_value_policy_t<LPs..., Policies...>;
+  using type_policy = resolved_type_policy_t<LPs..., Policies...>;
+  using error_policy = resolved_error_policy_t<LPs..., Policies...>;
+  using concurrency_policy = resolved_concurrency_policy_t<LPs..., Policies...>;
+
+  using rep_type =
+    type_policy_behavior<type_policy, sub_tag>::template result_type<L, R>;
+  using result_type = primitive<rep_type, LPs...>;
+
+  static constexpr result_type invoke(primitive<L, LPs...> const &lhs,
+                                      primitive<R, RPs...> const &rhs) noexcept {
+    return result_type{concurrency_policy_behavior<concurrency_policy, sub_tag>::execute(
+        [&]() constexpr noexcept {
+          return error_policy_behavior<error_policy, sub_tag>::template evaluate<rep_type>(
+              [&]() constexpr noexcept {
+                return value_policy_behavior<value_policy, sub_tag>::template sub<rep_type>(
+                    type_policy_behavior<type_policy, sub_tag>::template cast_lhs<rep_type>(
+                        lhs.value()),
+                    type_policy_behavior<type_policy, sub_tag>::template cast_rhs<rep_type>(
+                        rhs.value()));
+              });
+        })};
+  }
+};
+
+template <underlying_type L, policy::policy_type... LPs, underlying_type R,
+          policy::policy_type... RPs, policy::policy_type... Policies>
+struct traits<mul_tag, primitive<L, LPs...>, primitive<R, RPs...>, Policies...> {
+  static constexpr bool enabled = true;
+  static constexpr bool noexcept_invocable = true;
+
+  using value_policy = resolved_value_policy_t<LPs..., Policies...>;
+  using type_policy = resolved_type_policy_t<LPs..., Policies...>;
+  using error_policy = resolved_error_policy_t<LPs..., Policies...>;
+  using concurrency_policy = resolved_concurrency_policy_t<LPs..., Policies...>;
+
+  using rep_type =
+    type_policy_behavior<type_policy, mul_tag>::template result_type<L, R>;
+  using result_type = primitive<rep_type, LPs...>;
+
+  static constexpr result_type invoke(primitive<L, LPs...> const &lhs,
+                                      primitive<R, RPs...> const &rhs) noexcept {
+    return result_type{concurrency_policy_behavior<concurrency_policy, mul_tag>::execute(
+        [&]() constexpr noexcept {
+          return error_policy_behavior<error_policy, mul_tag>::template evaluate<rep_type>(
+              [&]() constexpr noexcept {
+                return value_policy_behavior<value_policy, mul_tag>::template mul<rep_type>(
+                    type_policy_behavior<type_policy, mul_tag>::template cast_lhs<rep_type>(
+                        lhs.value()),
+                    type_policy_behavior<type_policy, mul_tag>::template cast_rhs<rep_type>(
+                        rhs.value()));
+              });
+        })};
+  }
+};
+
+struct add_fn {
+  template <policy::policy_type... Policies, typename L, typename R>
+    requires binary_operation<add_tag, L, R, Policies...>
+  constexpr auto operator()(L &&lhs, R &&rhs) const
+      noexcept(nothrow_binary_operation<add_tag, L, R, Policies...>)
+          -> result_t<add_tag, L, R, Policies...> {
+    using impl =
+        traits<add_tag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
+               Policies...>;
+    return impl::invoke(lhs, rhs);
+  }
+};
+
+struct sub_fn {
+  template <policy::policy_type... Policies, typename L, typename R>
+    requires binary_operation<sub_tag, L, R, Policies...>
+  constexpr auto operator()(L &&lhs, R &&rhs) const
+      noexcept(nothrow_binary_operation<sub_tag, L, R, Policies...>)
+          -> result_t<sub_tag, L, R, Policies...> {
+    using impl =
+        traits<sub_tag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
+               Policies...>;
+    return impl::invoke(lhs, rhs);
+  }
+};
+
+struct mul_fn {
+  template <policy::policy_type... Policies, typename L, typename R>
+    requires binary_operation<mul_tag, L, R, Policies...>
+  constexpr auto operator()(L &&lhs, R &&rhs) const
+      noexcept(nothrow_binary_operation<mul_tag, L, R, Policies...>)
+          -> result_t<mul_tag, L, R, Policies...> {
+    using impl =
+        traits<mul_tag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
+               Policies...>;
+    return impl::invoke(lhs, rhs);
+  }
+};
+
+inline constexpr add_fn add{};
+inline constexpr sub_fn sub{};
+inline constexpr mul_fn mul{};
+
+} // namespace mcpplibs::primitives::operations
diff --git a/src/operations/operations.cppm b/src/operations/operations.cppm
new file mode 100644
index 0000000..b69683e
--- /dev/null
+++ b/src/operations/operations.cppm
@@ -0,0 +1,6 @@
+module;
+
+export module mcpplibs.primitives.operations;
+
+export import mcpplibs.primitives.operations.traits;
+export import mcpplibs.primitives.operations.impl;
\ No newline at end of file
diff --git a/src/operations/traits.cppm b/src/operations/traits.cppm
new file mode 100644
index 0000000..ac18323
--- /dev/null
+++ b/src/operations/traits.cppm
@@ -0,0 +1,168 @@
+module;
+#include <tuple>
+#include <type_traits>
+#include <utility>
+
+export module mcpplibs.primitives.operations.traits;
+
+import mcpplibs.primitives.policy;
+import mcpplibs.primitives.primitive;
+import mcpplibs.primitives.underlying;
+
+export namespace mcpplibs::primitives::operations {
+
+struct add_tag {};
+struct sub_tag {};
+struct mul_tag {};
+
+template <typename OpTag, typename L, typename R, typename... Policies>
+struct traits {
+  static constexpr bool enabled = false;
+  static constexpr bool noexcept_invocable = false;
+  using result_type = void;
+};
+
+template <typename OpTag, typename L, typename R, typename... Policies>
+concept binary_operation =
+    traits<OpTag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
+           Policies...>::enabled;
+
+template <typename OpTag, typename L, typename R, typename... Policies>
+concept nothrow_binary_operation =
+    binary_operation<OpTag, L, R, Policies...> &&
+    traits<OpTag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
+           Policies...>::noexcept_invocable;
+
+template <typename OpTag, typename L, typename R, typename... Policies>
+using result_t =
+  traits<OpTag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
+         Policies...>::result_type;
+
+namespace details {
+
+template <typename Fallback, typename... Policies>
+struct first_value_policy_impl {
+  using type = Fallback;
+};
+
+template <typename Fallback, typename First, typename... Rest>
+struct first_value_policy_impl<Fallback, First, Rest...> {
+  using type = std::conditional_t<
+      policy::value_policy<First>, First,
+      typename first_value_policy_impl<Fallback, Rest...>::type>;
+};
+
+template <typename Fallback, typename... Policies>
+struct first_type_policy_impl {
+  using type = Fallback;
+};
+
+template <typename Fallback, typename First, typename... Rest>
+struct first_type_policy_impl<Fallback, First, Rest...> {
+  using type = std::conditional_t<
+      policy::type_policy<First>, First,
+      typename first_type_policy_impl<Fallback, Rest...>::type>;
+};
+
+template <typename Fallback, typename... Policies>
+struct first_error_policy_impl {
+  using type = Fallback;
+};
+
+template <typename Fallback, typename First, typename... Rest>
+struct first_error_policy_impl<Fallback, First, Rest...> {
+  using type = std::conditional_t<
+      policy::error_policy<First>, First,
+      typename first_error_policy_impl<Fallback, Rest...>::type>;
+};
+
+template <typename Fallback, typename... Policies>
+struct first_concurrency_policy_impl {
+  using type = Fallback;
+};
+
+template <typename Fallback, typename First, typename... Rest>
+struct first_concurrency_policy_impl<Fallback, First, Rest...> {
+  using type = std::conditional_t<
+      policy::concurrency_policy<First>, First,
+      typename first_concurrency_policy_impl<Fallback, Rest...>::type>;
+};
+
+} // namespace details
+
+template <policy::value_policy ValuePolicy, typename OpTag = void>
+struct value_policy_behavior {
+  template <typename T>
+  static constexpr T add(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs + rhs);
+  }
+
+  template <typename T>
+  static constexpr T sub(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs - rhs);
+  }
+
+  template <typename T>
+  static constexpr T mul(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs * rhs);
+  }
+};
+
+template <policy::type_policy TypePolicy, typename OpTag = void>
+struct type_policy_behavior {
+  template <typename L, typename R>
+  using result_type = std::common_type_t<L, R>;
+
+  template <typename Out, typename In>
+  static constexpr Out cast_lhs(In const &value) noexcept {
+    return static_cast<Out>(value);
+  }
+
+  template <typename Out, typename In>
+  static constexpr Out cast_rhs(In const &value) noexcept {
+    return static_cast<Out>(value);
+  }
+};
+
+template <policy::error_policy ErrorPolicy, typename OpTag = void>
+struct error_policy_behavior {
+  template <typename Result, typename Fn>
+  static constexpr Result evaluate(Fn &&fn) noexcept(noexcept(fn())) {
+    return static_cast<Result>(std::forward<Fn>(fn)());
+  }
+};
+
+template <policy::concurrency_policy ConcurrencyPolicy, typename OpTag = void>
+struct concurrency_policy_behavior {
+  template <typename Fn>
+  static constexpr auto execute(Fn &&fn) noexcept(noexcept(fn()))
+      -> decltype(fn()) {
+    return std::forward<Fn>(fn)();
+  }
+};
+
+template <typename... Policies>
+using resolved_value_policy_t =
+  details::first_value_policy_impl<
+        std::tuple_element_t<0, policy::common_policies_t<Policies...>>,
+        Policies...>::type;
+
+template <typename... Policies>
+using resolved_type_policy_t =
+  details::first_type_policy_impl<
+        std::tuple_element_t<1, policy::common_policies_t<Policies...>>,
+        Policies...>::type;
+
+template <typename... Policies>
+using resolved_error_policy_t =
+  details::first_error_policy_impl<
+        std::tuple_element_t<2, policy::common_policies_t<Policies...>>,
+        Policies...>::type;
+
+template <typename... Policies>
+using resolved_concurrency_policy_t =
+  details::first_concurrency_policy_impl<
+        std::tuple_element_t<3, policy::common_policies_t<Policies...>>,
+        Policies...>::type;
+
+} // namespace mcpplibs::primitives::operations
diff --git a/src/primitives.cppm b/src/primitives.cppm
index 7a67d97..72e168e 100644
--- a/src/primitives.cppm
+++ b/src/primitives.cppm
@@ -4,4 +4,5 @@ export module mcpplibs.primitives;
 
 export import mcpplibs.primitives.underlying;
 export import mcpplibs.primitives.policy;
-export import mcpplibs.primitives.primitive;
\ No newline at end of file
+export import mcpplibs.primitives.primitive;
+export import mcpplibs.primitives.operations;
\ No newline at end of file

From 512ba53a561ba70bd5cd06ada6d4013d25b0930e Mon Sep 17 00:00:00 2001
From: FrozenlemonTee <1115306170@qq.com>
Date: Sun, 15 Mar 2026 23:14:02 +0800
Subject: [PATCH 3/7] feat: Add tests for new submodule operations

---
 tests/basic/test_operations.cpp | 185 ++++++++++++++++++++++++++++++++
 1 file changed, 185 insertions(+)
 create mode 100644 tests/basic/test_operations.cpp

diff --git a/tests/basic/test_operations.cpp b/tests/basic/test_operations.cpp
new file mode 100644
index 0000000..a74c136
--- /dev/null
+++ b/tests/basic/test_operations.cpp
@@ -0,0 +1,185 @@
+#include <limits>
+#include <type_traits>
+#include <gtest/gtest.h>
+
+import mcpplibs.primitives;
+
+using namespace mcpplibs::primitives;
+
+namespace {
+
+struct debug_value_policy {};
+struct debug_type_policy {};
+struct debug_error_policy {};
+struct debug_concurrency_policy {};
+
+} // namespace
+
+template <>
+struct policy::traits<debug_value_policy> {
+  using policy_type = debug_value_policy;
+  static constexpr bool enabled = true;
+  static constexpr auto kind = category::value;
+};
+
+template <>
+struct policy::traits<debug_type_policy> {
+  using policy_type = debug_type_policy;
+  static constexpr bool enabled = true;
+  static constexpr auto kind = category::type;
+};
+
+template <>
+struct policy::traits<debug_error_policy> {
+  using policy_type = debug_error_policy;
+  static constexpr bool enabled = true;
+  static constexpr auto kind = category::error;
+};
+
+template <>
+struct policy::traits<debug_concurrency_policy> {
+  using policy_type = debug_concurrency_policy;
+  static constexpr bool enabled = true;
+  static constexpr auto kind =
+      category::concurrency;
+};
+
+template <typename OpTag>
+struct operations::value_policy_behavior<
+    debug_value_policy, OpTag> {
+  template <typename T>
+  static constexpr T add(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs + rhs + 100);
+  }
+
+  template <typename T>
+  static constexpr T sub(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs - rhs - 100);
+  }
+
+  template <typename T>
+  static constexpr T mul(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs * rhs * 2);
+  }
+};
+
+template <typename OpTag>
+struct operations::type_policy_behavior<
+    debug_type_policy, OpTag> {
+  template <typename L, typename R>
+  using result_type = long long;
+
+  template <typename Out, typename In>
+  static constexpr Out cast_lhs(In const &value) noexcept {
+    return static_cast<Out>(value + 1);
+  }
+
+  template <typename Out, typename In>
+  static constexpr Out cast_rhs(In const &value) noexcept {
+    return static_cast<Out>(value + 2);
+  }
+};
+
+template <typename OpTag>
+struct operations::error_policy_behavior<
+    debug_error_policy, OpTag> {
+  template <typename Result, typename Fn>
+  static constexpr Result evaluate(Fn &&fn) noexcept(noexcept(fn())) {
+    return static_cast<Result>(fn() + static_cast<Result>(1000));
+  }
+};
+
+template <typename OpTag>
+struct operations::concurrency_policy_behavior<
+    debug_concurrency_policy, OpTag> {
+  template <typename Fn>
+  static constexpr auto execute(Fn &&fn) noexcept(noexcept(fn()))
+      -> decltype(fn()) {
+    return fn() + 7;
+  }
+};
+
+
+
+template <>
+struct operations::value_policy_behavior<
+    debug_value_policy, operations::add_tag> {
+  template <typename T>
+  static constexpr T add(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs + rhs + 200);
+  }
+
+  template <typename T>
+  static constexpr T sub(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs - rhs - 100);
+  }
+
+  template <typename T>
+  static constexpr T mul(T lhs, T rhs) noexcept {
+    return static_cast<T>(lhs * rhs * 2);
+  }
+};
+
+TEST(OperationsTest, UnderlyingOperationsWork) {
+  static_assert(operations::binary_operation<operations::add_tag, int, int>);
+  static_assert(operations::binary_operation<operations::sub_tag, int, int>);
+  static_assert(operations::binary_operation<operations::mul_tag, int, int>);
+
+  EXPECT_EQ(operations::add(2, 3), 5);
+  EXPECT_EQ(operations::sub(9, 4), 5);
+  EXPECT_EQ(operations::mul(3, 4), 12);
+}
+
+TEST(OperationsTest, PrimitiveOperationsWork) {
+  using namespace mcpplibs::primitives::types;
+
+  using lhs_t = I8<>;
+  using rhs_t = I8<>;
+
+  lhs_t lhs{10};
+  rhs_t rhs{5};
+
+  auto added = operations::add(lhs, rhs);
+  auto subed = operations::sub(lhs, rhs);
+  auto muled = operations::mul(lhs, rhs);
+
+  EXPECT_EQ(added.value(), 15);
+  EXPECT_EQ(subed.value(), 5);
+  EXPECT_EQ(muled.value(), 50);
+}
+
+TEST(OperationsTest, PolicyBehaviorTraitsCoverAllPolicyCategories) {
+  EXPECT_EQ((operations::add.operator()<
+                 debug_value_policy, debug_type_policy, debug_error_policy,
+                 debug_concurrency_policy>(2, 3)),
+            1215);
+  EXPECT_EQ((operations::sub.operator()<
+                 debug_value_policy, debug_type_policy, debug_error_policy,
+                 debug_concurrency_policy>(9, 4)),
+            911);
+  EXPECT_EQ((operations::mul.operator()<
+                 debug_value_policy, debug_type_policy, debug_error_policy,
+                 debug_concurrency_policy>(3, 4)),
+            1055);
+}
+
+
+TEST(OperationsTest, BuiltinPolicyTagsAreSpecialized) {
+  static_assert(std::is_same_v<
+      operations::result_t<operations::add_tag, int, int, policy::strict_type>,
+      int>);
+  static_assert(std::is_same_v<
+      operations::result_t<operations::add_tag, int, double,
+                           policy::transparent_type>,
+      double>);
+
+  constexpr int kMax = std::numeric_limits<int>::max();
+  constexpr int kMin = std::numeric_limits<int>::min();
+
+  EXPECT_EQ((operations::add.operator()<policy::saturating_value>(kMax, 1)),
+            kMax);
+  EXPECT_EQ((operations::sub.operator()<policy::saturating_value>(kMin, 1)),
+            kMin);
+  EXPECT_EQ((operations::mul.operator()<policy::saturating_value>(kMax, 2)),
+            kMax);
+}

From 628a8bcf5d12e249b26481d1ba6af10c7203c884 Mon Sep 17 00:00:00 2001
From: FrozenlemonTee <1115306170@qq.com>
Date: Sun, 15 Mar 2026 23:17:31 +0800
Subject: [PATCH 4/7] refactor: Add missing concepts

---
 src/underlying/traits.cppm | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/underlying/traits.cppm b/src/underlying/traits.cppm
index 93353cf..f248bd9 100644
--- a/src/underlying/traits.cppm
+++ b/src/underlying/traits.cppm
@@ -25,6 +25,9 @@ template <typename T>
 concept std_integer =
     std::integral<std::remove_cv_t<T>> && (!std_bool<T>) && (!std_char<T>);
 
+template <typename T>
+concept std_numeric = std_integer<T> || std_floating<T>;    
+
 template <typename T>
 concept std_underlying_type =
     std_bool<T> || std_char<T> || std_integer<T> || std_floating<T>;
@@ -122,5 +125,27 @@ concept underlying_type =
     underlying::details::has_std_rep_type<T> &&
     underlying::details::has_consistent_category<T>;
 
+template <typename T>
+concept boolean_underlying_type =
+    underlying_type<T> && (underlying::traits<std::remove_cv_t<T>>::kind ==
+                          underlying::category::boolean);    
+
+template <typename T>
+concept character_underlying_type =
+    underlying_type<T> && (underlying::traits<std::remove_cv_t<T>>::kind ==
+                          underlying::category::character);    
+
+template <typename T>
+concept integer_underlying_type =
+    underlying_type<T> && (underlying::traits<std::remove_cv_t<T>>::kind ==
+                          underlying::category::integer);    
+
+template <typename T>
+concept floating_underlying_type =
+    underlying_type<T> && (underlying::traits<std::remove_cv_t<T>>::kind ==
+                          underlying::category::floating);    
+
+template <typename T>
+concept numeric_underlying_type = integer_underlying_type<T> || floating_underlying_type<T>;
 } // namespace mcpplibs::primitives
 

From 0ff65de2e1e448cd3a3b0bd8f075139540c72624 Mon Sep 17 00:00:00 2001
From: FrozenlemonTee <1115306170@qq.com>
Date: Sun, 15 Mar 2026 23:18:32 +0800
Subject: [PATCH 5/7] refactor: Add type aliases

---
 src/primitive/impl.cppm | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/primitive/impl.cppm b/src/primitive/impl.cppm
index 3737bfb..4c1fa23 100644
--- a/src/primitive/impl.cppm
+++ b/src/primitive/impl.cppm
@@ -1,4 +1,5 @@
 module;
+#include <cstdint>
 #include <tuple>
 
 export module mcpplibs.primitives.primitive.impl;
@@ -21,4 +22,44 @@ private:
   value_type value_;
 };
 
+    namespace types {
+        template <policy::policy_type... Policies>
+        using Bool = primitive<bool, Policies...>;
+
+        template <policy::policy_type... Policies>
+        using UChar = primitive<unsigned char, Policies...>;
+        template <policy::policy_type... Policies>
+        using Char8 = primitive<char8_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using Char16 = primitive<char16_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using Char32 = primitive<char32_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using WChar = primitive<wchar_t, Policies...>;
+
+        template <policy::policy_type... Policies>
+        using U8 = primitive<std::uint8_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using U16 = primitive<std::uint16_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using U32 = primitive<std::uint32_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using U64 = primitive<std::uint64_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using I8 = primitive<std::int8_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using I16 = primitive<std::int16_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using I32 = primitive<std::int32_t, Policies...>;
+        template <policy::policy_type... Policies>
+        using I64 = primitive<std::int64_t, Policies...>;
+
+        template <policy::policy_type... Policies>
+        using F32 = primitive<float, Policies...>;
+        template <policy::policy_type... Policies>
+        using F64 = primitive<double, Policies...>;
+        template <policy::policy_type... Policies>
+        using F80 = primitive<long double, Policies...>;
+    }
+
 } // namespace mcpplibs::primitives

From e68d725cfd392935fb689a0822ffad3368b34e86 Mon Sep 17 00:00:00 2001
From: FrozenlemonTee <1115306170@qq.com>
Date: Mon, 16 Mar 2026 00:42:13 +0800
Subject: [PATCH 6/7] fix: Fix issue in operations

---
 src/operations/impl.cppm       | 374 ++++++++++++++++++++-------------
 src/operations/operations.cppm |   3 +-
 2 files changed, 234 insertions(+), 143 deletions(-)

diff --git a/src/operations/impl.cppm b/src/operations/impl.cppm
index dc53e31..647f1b4 100644
--- a/src/operations/impl.cppm
+++ b/src/operations/impl.cppm
@@ -1,8 +1,10 @@
 module;
 #include <atomic>
 #include <concepts>
+#include <expected>
 #include <exception>
 #include <limits>
+#include <stdexcept>
 #include <type_traits>
 
 export module mcpplibs.primitives.operations.impl;
@@ -17,7 +19,15 @@ export namespace mcpplibs::primitives::operations {
 namespace details {
 
 template <typename T>
-constexpr bool add_overflow(T lhs, T rhs) noexcept {
+struct is_expected : std::false_type {};
+
+template <typename V, typename E>
+struct is_expected<std::expected<V, E>> : std::true_type {};
+
+template <typename T>
+inline constexpr bool is_expected_v = is_expected<T>::value;
+
+template <typename T> constexpr bool add_overflow(T lhs, T rhs) noexcept {
   if constexpr (!std::is_integral_v<T>) {
     return false;
   } else if constexpr (std::is_signed_v<T>) {
@@ -30,8 +40,7 @@ constexpr bool add_overflow(T lhs, T rhs) noexcept {
   }
 }
 
-template <typename T>
-constexpr bool sub_overflow(T lhs, T rhs) noexcept {
+template <typename T> constexpr bool sub_overflow(T lhs, T rhs) noexcept {
   if constexpr (!std::is_integral_v<T>) {
     return false;
   } else if constexpr (std::is_signed_v<T>) {
@@ -43,8 +52,7 @@ constexpr bool sub_overflow(T lhs, T rhs) noexcept {
   }
 }
 
-template <typename T>
-constexpr bool mul_overflow(T lhs, T rhs) noexcept {
+template <typename T> constexpr bool mul_overflow(T lhs, T rhs) noexcept {
   if constexpr (!std::is_integral_v<T>) {
     return false;
   } else if (lhs == 0 || rhs == 0) {
@@ -58,8 +66,7 @@ constexpr bool mul_overflow(T lhs, T rhs) noexcept {
       return lhs == limits::min();
     }
     if (lhs > 0) {
-      return (rhs > 0) ? lhs > limits::max() / rhs
-                       : rhs < limits::min() / lhs;
+      return (rhs > 0) ? lhs > limits::max() / rhs : rhs < limits::min() / lhs;
     }
     return (rhs > 0) ? lhs < limits::min() / rhs
                      : lhs != 0 && rhs < limits::max() / lhs;
@@ -69,8 +76,7 @@ constexpr bool mul_overflow(T lhs, T rhs) noexcept {
   }
 }
 
-template <typename T>
-constexpr T saturating_add(T lhs, T rhs) noexcept {
+template <typename T> constexpr T saturating_add(T lhs, T rhs) noexcept {
   if constexpr (!std::is_integral_v<T>) {
     return static_cast<T>(lhs + rhs);
   } else {
@@ -86,8 +92,7 @@ constexpr T saturating_add(T lhs, T rhs) noexcept {
   }
 }
 
-template <typename T>
-constexpr T saturating_sub(T lhs, T rhs) noexcept {
+template <typename T> constexpr T saturating_sub(T lhs, T rhs) noexcept {
   if constexpr (!std::is_integral_v<T>) {
     return static_cast<T>(lhs - rhs);
   } else {
@@ -103,8 +108,7 @@ constexpr T saturating_sub(T lhs, T rhs) noexcept {
   }
 }
 
-template <typename T>
-constexpr T saturating_mul(T lhs, T rhs) noexcept {
+template <typename T> constexpr T saturating_mul(T lhs, T rhs) noexcept {
   if constexpr (!std::is_integral_v<T>) {
     return static_cast<T>(lhs * rhs);
   } else {
@@ -126,54 +130,54 @@ constexpr T saturating_mul(T lhs, T rhs) noexcept {
 
 template <typename OpTag>
 struct value_policy_behavior<policy::checked_value, OpTag> {
-  template <typename T>
-  static constexpr T add(T lhs, T rhs) noexcept {
+  template <typename T> static T add(T lhs, T rhs) {
+    if (details::add_overflow<T>(lhs, rhs)) {
+      throw std::overflow_error("overflow in add");
+    }
     return static_cast<T>(lhs + rhs);
   }
 
-  template <typename T>
-  static constexpr T sub(T lhs, T rhs) noexcept {
+  template <typename T> static T sub(T lhs, T rhs) {
+    if (details::sub_overflow<T>(lhs, rhs)) {
+      throw std::overflow_error("overflow in sub");
+    }
     return static_cast<T>(lhs - rhs);
   }
 
-  template <typename T>
-  static constexpr T mul(T lhs, T rhs) noexcept {
+  template <typename T> static T mul(T lhs, T rhs) {
+    if (details::mul_overflow<T>(lhs, rhs)) {
+      throw std::overflow_error("overflow in mul");
+    }
     return static_cast<T>(lhs * rhs);
   }
 };
 
 template <typename OpTag>
 struct value_policy_behavior<policy::unchecked_value, OpTag> {
-  template <typename T>
-  static constexpr T add(T lhs, T rhs) noexcept {
+  template <typename T> static constexpr T add(T lhs, T rhs) noexcept {
     return static_cast<T>(lhs + rhs);
   }
 
-  template <typename T>
-  static constexpr T sub(T lhs, T rhs) noexcept {
+  template <typename T> static constexpr T sub(T lhs, T rhs) noexcept {
     return static_cast<T>(lhs - rhs);
   }
 
-  template <typename T>
-  static constexpr T mul(T lhs, T rhs) noexcept {
+  template <typename T> static constexpr T mul(T lhs, T rhs) noexcept {
     return static_cast<T>(lhs * rhs);
   }
 };
 
 template <typename OpTag>
 struct value_policy_behavior<policy::saturating_value, OpTag> {
-  template <typename T>
-  static constexpr T add(T lhs, T rhs) noexcept {
+  template <typename T> static constexpr T add(T lhs, T rhs) noexcept {
     return details::saturating_add(lhs, rhs);
   }
 
-  template <typename T>
-  static constexpr T sub(T lhs, T rhs) noexcept {
+  template <typename T> static constexpr T sub(T lhs, T rhs) noexcept {
     return details::saturating_sub(lhs, rhs);
   }
 
-  template <typename T>
-  static constexpr T mul(T lhs, T rhs) noexcept {
+  template <typename T> static constexpr T mul(T lhs, T rhs) noexcept {
     return details::saturating_mul(lhs, rhs);
   }
 };
@@ -182,8 +186,7 @@ struct value_policy_behavior<policy::saturating_value, OpTag> {
 
 template <typename OpTag>
 struct type_policy_behavior<policy::strict_type, OpTag> {
-  template <typename L, typename R>
-  using result_type = std::remove_cv_t<L>;
+  template <typename L, typename R> using result_type = std::remove_cv_t<L>;
 
   template <typename Out, typename In>
   static constexpr Out cast_lhs(In const &value) noexcept {
@@ -210,10 +213,9 @@ struct type_policy_behavior<policy::category_compatible_type, OpTag> {
 
   template <typename Out, typename In>
   static constexpr Out cast_rhs(In const &value) noexcept {
-    static_assert(
-        underlying::traits<std::remove_cv_t<Out>>::kind ==
-            underlying::traits<std::remove_cv_t<In>>::kind,
-        "category_compatible_type requires same underlying category");
+    static_assert(underlying::traits<std::remove_cv_t<Out>>::kind ==
+                      underlying::traits<std::remove_cv_t<In>>::kind,
+                  "category_compatible_type requires same underlying category");
     return static_cast<Out>(value);
   }
 };
@@ -248,7 +250,11 @@ template <typename OpTag>
 struct error_policy_behavior<policy::expected_error, OpTag> {
   template <typename Result, typename Fn>
   static constexpr Result evaluate(Fn &&fn) noexcept(noexcept(fn())) {
-    return static_cast<Result>(fn());
+    if constexpr (details::is_expected_v<Result>) {
+      return Result{std::in_place, std::forward<Fn>(fn)()};
+    } else {
+      return static_cast<Result>(fn());
+    }
   }
 };
 
@@ -303,20 +309,21 @@ struct traits<add_tag, L, R, Policies...> {
   using concurrency_policy = resolved_concurrency_policy_t<Policies...>;
 
   using result_type =
-    type_policy_behavior<type_policy, add_tag>::template result_type<L, R>;
+      type_policy_behavior<type_policy, add_tag>::template result_type<L, R>;
 
   static constexpr result_type invoke(L const &lhs, R const &rhs) noexcept {
-    return concurrency_policy_behavior<concurrency_policy, add_tag>::execute(
-        [&]() constexpr noexcept {
-          return error_policy_behavior<error_policy, add_tag>::template evaluate<
-              result_type>([&]() constexpr noexcept {
-            return value_policy_behavior<value_policy, add_tag>::template add<result_type>(
-                type_policy_behavior<type_policy, add_tag>::template cast_lhs<result_type>(
-                    lhs),
-                type_policy_behavior<type_policy, add_tag>::template cast_rhs<result_type>(
-                    rhs));
-          });
-        });
+    return concurrency_policy_behavior<
+        concurrency_policy, add_tag>::execute([&]() constexpr noexcept {
+      return error_policy_behavior<error_policy, add_tag>::template evaluate<
+          result_type>([&]() constexpr noexcept {
+        return value_policy_behavior<value_policy, add_tag>::template add<
+            result_type>(
+            type_policy_behavior<type_policy,
+                                 add_tag>::template cast_lhs<result_type>(lhs),
+            type_policy_behavior<type_policy,
+                                 add_tag>::template cast_rhs<result_type>(rhs));
+      });
+    });
   }
 };
 
@@ -331,20 +338,21 @@ struct traits<sub_tag, L, R, Policies...> {
   using concurrency_policy = resolved_concurrency_policy_t<Policies...>;
 
   using result_type =
-    type_policy_behavior<type_policy, sub_tag>::template result_type<L, R>;
+      type_policy_behavior<type_policy, sub_tag>::template result_type<L, R>;
 
   static constexpr result_type invoke(L const &lhs, R const &rhs) noexcept {
-    return concurrency_policy_behavior<concurrency_policy, sub_tag>::execute(
-        [&]() constexpr noexcept {
-          return error_policy_behavior<error_policy, sub_tag>::template evaluate<
-              result_type>([&]() constexpr noexcept {
-            return value_policy_behavior<value_policy, sub_tag>::template sub<result_type>(
-                type_policy_behavior<type_policy, sub_tag>::template cast_lhs<result_type>(
-                    lhs),
-                type_policy_behavior<type_policy, sub_tag>::template cast_rhs<result_type>(
-                    rhs));
-          });
-        });
+    return concurrency_policy_behavior<
+        concurrency_policy, sub_tag>::execute([&]() constexpr noexcept {
+      return error_policy_behavior<error_policy, sub_tag>::template evaluate<
+          result_type>([&]() constexpr noexcept {
+        return value_policy_behavior<value_policy, sub_tag>::template sub<
+            result_type>(
+            type_policy_behavior<type_policy,
+                                 sub_tag>::template cast_lhs<result_type>(lhs),
+            type_policy_behavior<type_policy,
+                                 sub_tag>::template cast_rhs<result_type>(rhs));
+      });
+    });
   }
 };
 
@@ -359,27 +367,29 @@ struct traits<mul_tag, L, R, Policies...> {
   using concurrency_policy = resolved_concurrency_policy_t<Policies...>;
 
   using result_type =
-    type_policy_behavior<type_policy, mul_tag>::template result_type<L, R>;
+      type_policy_behavior<type_policy, mul_tag>::template result_type<L, R>;
 
   static constexpr result_type invoke(L const &lhs, R const &rhs) noexcept {
-    return concurrency_policy_behavior<concurrency_policy, mul_tag>::execute(
-        [&]() constexpr noexcept {
-          return error_policy_behavior<error_policy, mul_tag>::template evaluate<
-              result_type>([&]() constexpr noexcept {
-            return value_policy_behavior<value_policy, mul_tag>::template mul<result_type>(
-                type_policy_behavior<type_policy, mul_tag>::template cast_lhs<result_type>(
-                    lhs),
-                type_policy_behavior<type_policy, mul_tag>::template cast_rhs<result_type>(
-                    rhs));
-          });
-        });
+    return concurrency_policy_behavior<
+        concurrency_policy, mul_tag>::execute([&]() constexpr noexcept {
+      return error_policy_behavior<error_policy, mul_tag>::template evaluate<
+          result_type>([&]() constexpr noexcept {
+        return value_policy_behavior<value_policy, mul_tag>::template mul<
+            result_type>(
+            type_policy_behavior<type_policy,
+                                 mul_tag>::template cast_lhs<result_type>(lhs),
+            type_policy_behavior<type_policy,
+                                 mul_tag>::template cast_rhs<result_type>(rhs));
+      });
+    });
   }
 };
 
 // primitive operations (keep lhs policy set by default)
 template <underlying_type L, policy::policy_type... LPs, underlying_type R,
           policy::policy_type... RPs, policy::policy_type... Policies>
-struct traits<add_tag, primitive<L, LPs...>, primitive<R, RPs...>, Policies...> {
+struct traits<add_tag, primitive<L, LPs...>, primitive<R, RPs...>,
+              Policies...> {
   static constexpr bool enabled = true;
   static constexpr bool noexcept_invocable = true;
 
@@ -390,27 +400,58 @@ struct traits<add_tag, primitive<L, LPs...>, primitive<R, RPs...>, Policies...>
 
   using rep_type =
       type_policy_behavior<type_policy, add_tag>::template result_type<L, R>;
-  using result_type = primitive<rep_type, LPs...>;
-
-  static constexpr result_type invoke(primitive<L, LPs...> const &lhs,
-                                      primitive<R, RPs...> const &rhs) noexcept {
-    return result_type{concurrency_policy_behavior<concurrency_policy, add_tag>::execute(
-        [&]() constexpr noexcept {
-          return error_policy_behavior<error_policy, add_tag>::template evaluate<rep_type>(
-              [&]() constexpr noexcept {
-                return value_policy_behavior<value_policy, add_tag>::template add<rep_type>(
-                    type_policy_behavior<type_policy, add_tag>::template cast_lhs<rep_type>(
-                        lhs.value()),
-                    type_policy_behavior<type_policy, add_tag>::template cast_rhs<rep_type>(
-                        rhs.value()));
-              });
-        })};
+    using raw_result_type = primitive<rep_type, LPs...>;
+    using result_type = std::conditional_t<
+      std::is_same_v<error_policy, policy::expected_error>,
+      std::expected<raw_result_type, std::overflow_error>, raw_result_type>;
+
+  static result_type invoke(primitive<L, LPs...> const &lhs,
+                            primitive<R, RPs...> const &rhs) {
+    // Prepare casted representations
+    rep_type lhs_rep =
+        type_policy_behavior<type_policy, add_tag>::template cast_lhs<rep_type>(
+            lhs.value());
+    rep_type rhs_rep =
+        type_policy_behavior<type_policy, add_tag>::template cast_rhs<rep_type>(
+            rhs.value());
+
+    // If value policy is checked, handle overflow according to error policy.
+    if constexpr (std::is_same_v<value_policy, policy::checked_value>) {
+      if (details::add_overflow<rep_type>(lhs_rep, rhs_rep)) {
+        if constexpr (std::is_same_v<error_policy, policy::throw_error>) {
+          throw std::overflow_error("overflow in add");
+        } else if constexpr (std::is_same_v<error_policy,
+                                            policy::terminate_error>) {
+          std::terminate();
+        } else if constexpr (std::is_same_v<error_policy,
+                                            policy::expected_error>) {
+          return std::unexpected(std::overflow_error("overflow in add"));
+        }
+      }
+    }
+
+    const auto rep = concurrency_policy_behavior<concurrency_policy,
+                                                 add_tag>::execute([&]() {
+      return error_policy_behavior<error_policy,
+                                   add_tag>::template evaluate<rep_type>([&]() {
+        return value_policy_behavior<value_policy,
+                                     add_tag>::template add<rep_type>(lhs_rep,
+                                                                      rhs_rep);
+      });
+    });
+
+    if constexpr (std::is_same_v<error_policy, policy::expected_error>) {
+      return raw_result_type{rep};
+    } else {
+      return raw_result_type{rep};
+    }
   }
 };
 
 template <underlying_type L, policy::policy_type... LPs, underlying_type R,
           policy::policy_type... RPs, policy::policy_type... Policies>
-struct traits<sub_tag, primitive<L, LPs...>, primitive<R, RPs...>, Policies...> {
+struct traits<sub_tag, primitive<L, LPs...>, primitive<R, RPs...>,
+              Policies...> {
   static constexpr bool enabled = true;
   static constexpr bool noexcept_invocable = true;
 
@@ -420,28 +461,56 @@ struct traits<sub_tag, primitive<L, LPs...>, primitive<R, RPs...>, Policies...>
   using concurrency_policy = resolved_concurrency_policy_t<LPs..., Policies...>;
 
   using rep_type =
-    type_policy_behavior<type_policy, sub_tag>::template result_type<L, R>;
-  using result_type = primitive<rep_type, LPs...>;
-
-  static constexpr result_type invoke(primitive<L, LPs...> const &lhs,
-                                      primitive<R, RPs...> const &rhs) noexcept {
-    return result_type{concurrency_policy_behavior<concurrency_policy, sub_tag>::execute(
-        [&]() constexpr noexcept {
-          return error_policy_behavior<error_policy, sub_tag>::template evaluate<rep_type>(
-              [&]() constexpr noexcept {
-                return value_policy_behavior<value_policy, sub_tag>::template sub<rep_type>(
-                    type_policy_behavior<type_policy, sub_tag>::template cast_lhs<rep_type>(
-                        lhs.value()),
-                    type_policy_behavior<type_policy, sub_tag>::template cast_rhs<rep_type>(
-                        rhs.value()));
-              });
-        })};
+      type_policy_behavior<type_policy, sub_tag>::template result_type<L, R>;
+    using raw_result_type = primitive<rep_type, LPs...>;
+    using result_type = std::conditional_t<
+      std::is_same_v<error_policy, policy::expected_error>,
+      std::expected<raw_result_type, std::overflow_error>, raw_result_type>;
+
+  static result_type invoke(primitive<L, LPs...> const &lhs,
+                            primitive<R, RPs...> const &rhs) {
+    rep_type lhs_rep =
+        type_policy_behavior<type_policy, sub_tag>::template cast_lhs<rep_type>(
+            lhs.value());
+    rep_type rhs_rep =
+        type_policy_behavior<type_policy, sub_tag>::template cast_rhs<rep_type>(
+            rhs.value());
+
+    if constexpr (std::is_same_v<value_policy, policy::checked_value>) {
+      if (details::sub_overflow<rep_type>(lhs_rep, rhs_rep)) {
+        if constexpr (std::is_same_v<error_policy, policy::throw_error>) {
+          throw std::overflow_error("overflow in sub");
+        } else if constexpr (std::is_same_v<error_policy,
+                                            policy::terminate_error>) {
+          std::terminate();
+        } else if constexpr (std::is_same_v<error_policy,
+                                            policy::expected_error>) {
+          return std::unexpected(std::overflow_error("overflow in sub"));
+        }
+      }
+    }
+
+    const auto rep = concurrency_policy_behavior<concurrency_policy,
+                                                 sub_tag>::execute([&]() {
+      return error_policy_behavior<error_policy,
+                                   sub_tag>::template evaluate<rep_type>([&]() {
+        return value_policy_behavior<value_policy, sub_tag>::template sub<
+            rep_type>(lhs_rep, rhs_rep);
+      });
+    });
+
+    if constexpr (std::is_same_v<error_policy, policy::expected_error>) {
+      return raw_result_type{rep};
+    } else {
+      return raw_result_type{rep};
+    }
   }
 };
 
 template <underlying_type L, policy::policy_type... LPs, underlying_type R,
           policy::policy_type... RPs, policy::policy_type... Policies>
-struct traits<mul_tag, primitive<L, LPs...>, primitive<R, RPs...>, Policies...> {
+struct traits<mul_tag, primitive<L, LPs...>, primitive<R, RPs...>,
+              Policies...> {
   static constexpr bool enabled = true;
   static constexpr bool noexcept_invocable = true;
 
@@ -451,34 +520,59 @@ struct traits<mul_tag, primitive<L, LPs...>, primitive<R, RPs...>, Policies...>
   using concurrency_policy = resolved_concurrency_policy_t<LPs..., Policies...>;
 
   using rep_type =
-    type_policy_behavior<type_policy, mul_tag>::template result_type<L, R>;
-  using result_type = primitive<rep_type, LPs...>;
-
-  static constexpr result_type invoke(primitive<L, LPs...> const &lhs,
-                                      primitive<R, RPs...> const &rhs) noexcept {
-    return result_type{concurrency_policy_behavior<concurrency_policy, mul_tag>::execute(
-        [&]() constexpr noexcept {
-          return error_policy_behavior<error_policy, mul_tag>::template evaluate<rep_type>(
-              [&]() constexpr noexcept {
-                return value_policy_behavior<value_policy, mul_tag>::template mul<rep_type>(
-                    type_policy_behavior<type_policy, mul_tag>::template cast_lhs<rep_type>(
-                        lhs.value()),
-                    type_policy_behavior<type_policy, mul_tag>::template cast_rhs<rep_type>(
-                        rhs.value()));
-              });
-        })};
+      type_policy_behavior<type_policy, mul_tag>::template result_type<L, R>;
+    using raw_result_type = primitive<rep_type, LPs...>;
+    using result_type = std::conditional_t<
+      std::is_same_v<error_policy, policy::expected_error>,
+      std::expected<raw_result_type, std::overflow_error>, raw_result_type>;
+
+  static result_type invoke(primitive<L, LPs...> const &lhs,
+                            primitive<R, RPs...> const &rhs) {
+    rep_type lhs_rep =
+        type_policy_behavior<type_policy, mul_tag>::template cast_lhs<rep_type>(
+            lhs.value());
+    rep_type rhs_rep =
+        type_policy_behavior<type_policy, mul_tag>::template cast_rhs<rep_type>(
+            rhs.value());
+
+    if constexpr (std::is_same_v<value_policy, policy::checked_value>) {
+      if (details::mul_overflow<rep_type>(lhs_rep, rhs_rep)) {
+        if constexpr (std::is_same_v<error_policy, policy::throw_error>) {
+          throw std::overflow_error("overflow in mul");
+        } else if constexpr (std::is_same_v<error_policy,
+                                            policy::terminate_error>) {
+          std::terminate();
+        } else if constexpr (std::is_same_v<error_policy,
+                                            policy::expected_error>) {
+          return std::unexpected(std::overflow_error("overflow in mul"));
+        }
+      }
+    }
+
+    const auto rep = concurrency_policy_behavior<concurrency_policy,
+                                                 mul_tag>::execute([&]() {
+      return error_policy_behavior<error_policy,
+                                   mul_tag>::template evaluate<rep_type>([&]() {
+        return value_policy_behavior<value_policy, mul_tag>::template mul<
+            rep_type>(lhs_rep, rhs_rep);
+      });
+    });
+
+    if constexpr (std::is_same_v<error_policy, policy::expected_error>) {
+      return raw_result_type{rep};
+    } else {
+      return raw_result_type{rep};
+    }
   }
 };
 
 struct add_fn {
   template <policy::policy_type... Policies, typename L, typename R>
     requires binary_operation<add_tag, L, R, Policies...>
-  constexpr auto operator()(L &&lhs, R &&rhs) const
-      noexcept(nothrow_binary_operation<add_tag, L, R, Policies...>)
-          -> result_t<add_tag, L, R, Policies...> {
-    using impl =
-        traits<add_tag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
-               Policies...>;
+  auto operator()(L &&lhs, R &&rhs) const
+      -> result_t<add_tag, L, R, Policies...> {
+    using impl = traits<add_tag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
+                        Policies...>;
     return impl::invoke(lhs, rhs);
   }
 };
@@ -486,12 +580,10 @@ struct add_fn {
 struct sub_fn {
   template <policy::policy_type... Policies, typename L, typename R>
     requires binary_operation<sub_tag, L, R, Policies...>
-  constexpr auto operator()(L &&lhs, R &&rhs) const
-      noexcept(nothrow_binary_operation<sub_tag, L, R, Policies...>)
-          -> result_t<sub_tag, L, R, Policies...> {
-    using impl =
-        traits<sub_tag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
-               Policies...>;
+  auto operator()(L &&lhs, R &&rhs) const
+      -> result_t<sub_tag, L, R, Policies...> {
+    using impl = traits<sub_tag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
+                        Policies...>;
     return impl::invoke(lhs, rhs);
   }
 };
@@ -499,12 +591,10 @@ struct sub_fn {
 struct mul_fn {
   template <policy::policy_type... Policies, typename L, typename R>
     requires binary_operation<mul_tag, L, R, Policies...>
-  constexpr auto operator()(L &&lhs, R &&rhs) const
-      noexcept(nothrow_binary_operation<mul_tag, L, R, Policies...>)
-          -> result_t<mul_tag, L, R, Policies...> {
-    using impl =
-        traits<mul_tag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
-               Policies...>;
+  auto operator()(L &&lhs, R &&rhs) const
+      -> result_t<mul_tag, L, R, Policies...> {
+    using impl = traits<mul_tag, std::remove_cvref_t<L>, std::remove_cvref_t<R>,
+                        Policies...>;
     return impl::invoke(lhs, rhs);
   }
 };
diff --git a/src/operations/operations.cppm b/src/operations/operations.cppm
index b69683e..f7efa82 100644
--- a/src/operations/operations.cppm
+++ b/src/operations/operations.cppm
@@ -3,4 +3,5 @@ module;
 export module mcpplibs.primitives.operations;
 
 export import mcpplibs.primitives.operations.traits;
-export import mcpplibs.primitives.operations.impl;
\ No newline at end of file
+export import mcpplibs.primitives.operations.impl;
+export import mcpplibs.primitives.operations.operators;
\ No newline at end of file

From b2bcf197fd69fbf9dbd191db99f3dde8f89f9850 Mon Sep 17 00:00:00 2001
From: FrozenlemonTee <1115306170@qq.com>
Date: Mon, 16 Mar 2026 00:43:23 +0800
Subject: [PATCH 7/7] docs: Update README.md and the example program

---
 README.md                     |  27 ++++++-
 examples/basic.cpp            |  52 +++++++++----
 src/operations/operators.cppm | 141 ++++++++++++++++++++++++++++++++++
 3 files changed, 205 insertions(+), 15 deletions(-)
 create mode 100644 src/operations/operators.cppm

diff --git a/README.md b/README.md
index 08e9550..3cb412f 100644
--- a/README.md
+++ b/README.md
@@ -4,14 +4,39 @@
 
 本仓库实现了底层强类型 primitive 基础设施（traits、policy、underlying 类型分类），供上层 `Integer`/`Floating`/`Boolean` 等封装使用。
 
+> [!WARNING]
+> 目前项目还在开发中，API会随着后续演进而改变
+
 ## 特性
 
-- **C++23 模块** — `import mcpplibs.templates;`
+- **C++23 模块** — `import mcpplibs.primitives;`
 - **双构建系统** — 同时支持 xmake 和 CMake
 - **CI/CD** — GitHub Actions 多平台构建（Linux / macOS / Windows）
 - **标准化结构** — 遵循 [mcpp-style-ref](https://github.com/mcpp-community/mcpp-style-ref) 编码规范
 - **开箱即用** — 包含示例、测试和架构文档
 
+## Operators
+
+该库在 `primitive` 类型上重载了常见的 C++ 算术、位运算和一元运算符。算术行为受策略（policy）控制：
+
+- 值策略（`checked_value` / `saturating_value` / `unchecked_value`）决定溢出行为；
+- 错误策略（`throw_error` / `expected_error` / `terminate_error`）决定在 `checked_value` 且发生错误时的处理方式。
+
+示例：
+
+```cpp
+import mcpplibs.primitives;
+using namespace mcpplibs::primitives;
+using namespace mcpplibs::primitives::policy;
+
+primitive<int> a{1}, b{2};
+auto c = a + b; // primitive<int>
+
+primitive<int, expected_error> x{std::numeric_limits<int>::max()};
+primitive<int, expected_error> y{1};
+auto maybe = x + y; // std::expected<primitive<int, expected_error>, std::overflow_error>
+```
+
 ## 项目结构
 
 ```
diff --git a/examples/basic.cpp b/examples/basic.cpp
index 89f7354..83b2790 100644
--- a/examples/basic.cpp
+++ b/examples/basic.cpp
@@ -1,26 +1,50 @@
 #include <iostream>
+#include <limits>
 
 import mcpplibs.primitives;
 
 int main() {
   using namespace mcpplibs::primitives;
   using namespace mcpplibs::primitives::policy;
+  using namespace mcpplibs::primitives::operators;
+  using namespace mcpplibs::primitives::types;
 
-  std::cout << "=== mcpplibs.primitives traits & policy example ===\n";
-  std::cout << std::boolalpha;
-  std::cout << "int is std_integer: " << std_integer<int> << "\n";
-  std::cout << "double is std_floating: " << std_floating<double> << "\n";
-  std::cout << "int is underlying_type: " << underlying_type<int> << "\n";
-
-  std::cout
-      << "default value policy is unchecked_value: "
-      << std::is_same_v<default_value, checked_value> << "\n";
-
-  std::cout << "checked_value is a policy_type: "
-            << policy_type<checked_value> << "\n";
-  std::cout << "checked_value category == value: "
-            << (policy::traits<checked_value>::kind == category::value)
+  // Operators
+  I32<> a{3};
+  I32<> b{4};
+  auto c = a + b; // primitive<int>
+  std::cout << "3 + 4 = " << static_cast<int>(c) << "\n";
+
+  // Error handling
+  I32<checked_value> lhs{1};
+  I32<checked_value> rhs{std::numeric_limits<std::int32_t>::max()};
+
+  try {
+    auto res = lhs + rhs;
+  } catch (const std::exception &e) {
+    std::cout << "An exception occurred: " << e.what() << "\n";
+  }
+
+  I64<checked_value, expected_error> lhs2{1};
+  I64<checked_value, expected_error> rhs2{std::numeric_limits<std::int64_t>::max()};
+
+  auto res2 = lhs2 + rhs2;
+
+  // Saturating
+  I32<saturating_value> s1{std::numeric_limits<std::int32_t>::max()};
+  I32<saturating_value> s2{1};
+  auto sat = s1 + s2; // saturating -> stays max
+  std::cout << "saturating max + 1 = " << static_cast<std::int32_t>(sat)
             << "\n";
 
+  // Mixed-type addition
+  using expected_type = I64<category_compatible_type>;
+  expected_type L1{5};
+  I32<category_compatible_type> L2{6};
+  auto mix = L1 + L2; // common_type -> I64
+  std::cout << "5 + 6 = " << mix.value() << "\n";
+  std::cout << std::boolalpha;
+  std::cout << "Does type of mix is I64<category_compatible_type>: " << std::same_as<decltype(mix), expected_type> << std::endl;
+
   return 0;
 }
diff --git a/src/operations/operators.cppm b/src/operations/operators.cppm
new file mode 100644
index 0000000..e7e9219
--- /dev/null
+++ b/src/operations/operators.cppm
@@ -0,0 +1,141 @@
+module;
+#include <type_traits>
+export module mcpplibs.primitives.operations.operators;
+
+import mcpplibs.primitives.underlying;
+import mcpplibs.primitives.policy;
+import mcpplibs.primitives.primitive;
+import mcpplibs.primitives.operations.impl;
+
+export namespace mcpplibs::primitives::operators {
+template <typename T, policy::policy_type... Policies>
+  requires std_numeric<T>
+constexpr auto operator~(const primitive<T, Policies...> &p) {
+  // Placeholder: unary bitwise NOT not yet forwarded to operations layer.
+  // TODO: forward to operations::bit_not when implemented.
+  return primitives::primitive<T, Policies...>(~p.value());
+}
+
+template <typename T, policy::policy_type... Policies>
+  requires std_numeric<T>
+constexpr auto operator+(const primitive<T, Policies...> &p) {
+  // Placeholder: unary plus not yet forwarded to operations layer.
+  // TODO: forward to operations::unary_plus when implemented.
+  return primitives::primitive<T, Policies...>(+p.value());
+}
+
+template <typename T, policy::policy_type... Policies>
+  requires std_numeric<T>
+constexpr auto operator-(const primitive<T, Policies...> &p) {
+  // Placeholder: unary minus not yet forwarded to operations layer.
+  // TODO: forward to operations::unary_neg when implemented.
+  return primitives::primitive<T, Policies...>(-p.value());
+}
+
+template <typename LHS, typename RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+  requires std_numeric<LHS> && std_numeric<RHS>
+constexpr auto operator+(const primitive<LHS, PoliciesLHS...> &lhs,
+                         const primitive<RHS, PoliciesRHS...> &rhs) {
+  return operations::add(lhs, rhs);
+}
+
+template <typename LHS, typename RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+  requires std_numeric<LHS> && std_numeric<RHS>
+constexpr auto operator-(const primitive<LHS, PoliciesLHS...> &lhs,
+                         const primitive<RHS, PoliciesRHS...> &rhs) {
+  return operations::sub(lhs, rhs);
+}
+
+template <std_numeric LHS, std_numeric RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+constexpr auto operator*(const primitive<LHS, PoliciesLHS...> &lhs,
+                         const primitive<RHS, PoliciesRHS...> &rhs) {
+  return operations::mul(lhs, rhs);
+}
+
+template <std_numeric LHS, std_numeric RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+constexpr auto operator/(const primitive<LHS, PoliciesLHS...> &lhs,
+                         const primitive<RHS, PoliciesRHS...> &rhs) {
+  // Placeholder: division not yet forwarded to operations layer.
+  // TODO: forward to operations::div when implemented (handle policies).
+  using result_type = std::common_type_t<LHS, RHS>;
+  return primitives::primitive<result_type, PoliciesLHS..., PoliciesRHS...>(
+      static_cast<result_type>(lhs.value()) /
+      static_cast<result_type>(rhs.value()));
+}
+
+template <std_numeric LHS, std_numeric RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+constexpr auto operator%(const primitive<LHS, PoliciesLHS...> &lhs,
+                         const primitive<RHS, PoliciesRHS...> &rhs) {
+  // Placeholder: modulo not yet forwarded to operations layer.
+  // TODO: forward to operations::mod when implemented (handle policies).
+  using result_type = std::common_type_t<LHS, RHS>;
+  return primitives::primitive<result_type, PoliciesLHS..., PoliciesRHS...>(
+      static_cast<result_type>(lhs.value()) %
+      static_cast<result_type>(rhs.value()));
+}
+
+template <std_numeric LHS, std_numeric RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+constexpr auto operator<<(const primitive<LHS, PoliciesLHS...> &lhs,
+                          const primitive<RHS, PoliciesRHS...> &rhs) {
+  // Placeholder: left shift not yet forwarded to operations layer.
+  // TODO: forward to operations::shl when implemented (handle policies).
+  using result_type = std::common_type_t<LHS, RHS>;
+  return primitives::primitive<result_type, PoliciesLHS..., PoliciesRHS...>(
+      static_cast<result_type>(lhs.value())
+      << static_cast<result_type>(rhs.value()));
+}
+
+template <std_numeric LHS, std_numeric RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+constexpr auto operator>>(const primitive<LHS, PoliciesLHS...> &lhs,
+                          const primitive<RHS, PoliciesRHS...> &rhs) {
+  // Placeholder: right shift not yet forwarded to operations layer.
+  // TODO: forward to operations::shr when implemented (handle policies).
+  using result_type = std::common_type_t<LHS, RHS>;
+  return primitives::primitive<result_type, PoliciesLHS..., PoliciesRHS...>(
+      static_cast<result_type>(lhs.value()) >>
+      static_cast<result_type>(rhs.value()));
+}
+
+template <std_numeric LHS, std_numeric RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+constexpr auto operator&(const primitive<LHS, PoliciesLHS...> &lhs,
+                         const primitive<RHS, PoliciesRHS...> &rhs) {
+  // Placeholder: bitwise AND not yet forwarded to operations layer.
+  // TODO: forward to operations::bit_and when implemented (handle policies).
+  using result_type = std::common_type_t<LHS, RHS>;
+  return primitives::primitive<result_type, PoliciesLHS..., PoliciesRHS...>(
+      static_cast<result_type>(lhs.value()) &
+      static_cast<result_type>(rhs.value()));
+}
+
+template <std_numeric LHS, std_numeric RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+constexpr auto operator|(const primitive<LHS, PoliciesLHS...> &lhs,
+                         const primitive<RHS, PoliciesRHS...> &rhs) {
+  // Placeholder: bitwise OR not yet forwarded to operations layer.
+  // TODO: forward to operations::bit_or when implemented (handle policies).
+  using result_type = std::common_type_t<LHS, RHS>;
+  return primitives::primitive<result_type, PoliciesLHS..., PoliciesRHS...>(
+      static_cast<result_type>(lhs.value()) |
+      static_cast<result_type>(rhs.value()));
+}
+
+template <std_numeric LHS, std_numeric RHS, policy::policy_type... PoliciesLHS,
+          policy::policy_type... PoliciesRHS>
+constexpr auto operator^(const primitive<LHS, PoliciesLHS...> &lhs,
+                         const primitive<RHS, PoliciesRHS...> &rhs) {
+  // Placeholder: bitwise XOR not yet forwarded to operations layer.
+  // TODO: forward to operations::bit_xor when implemented (handle policies).
+  using result_type = std::common_type_t<LHS, RHS>;
+  return primitives::primitive<result_type, PoliciesLHS..., PoliciesRHS...>(
+      static_cast<result_type>(lhs.value()) ^
+      static_cast<result_type>(rhs.value()));
+}
+} // namespace mcpplibs::primitives::operators
\ No newline at end of file