Simplify the interface and hide internal implementations that do not need to be exported

.agents/docs/plans/implementation-plan.md

@@ -0,0 +1,82 @@
+# Primitives 下一步实现计划清单（2026-03-23）
+
+## 总体原则
+
+- [ ] 先定义稳定 API 边界，再落地实现
+- [ ] 每个能力都配套 tests + examples + docs
+- [ ] 高风险转换默认禁止隐式触发，只允许显式 API
+
+## M1. C API 互操作层（双向）
+
+### 工作清单
+
+- [ ] 定义稳定 C ABI（命名规范、导出宏、版本策略）
+- [ ] 设计双向能力：C 调用 primitives；primitives 适配并调用 C API
+- [ ] 统一错误模型（error code + 可选 message buffer）
+- [ ] 提供最小可用头文件：`include/mcpplibs/primitives/c_api.h`
+- [ ] 增加 C/C++ 混合构建测试（C 编译器 + C++ 链接）
+- [ ] 增加示例：`examples/c/basic.c`、`examples/cpp/use_c_api.cpp`
+
+### 验收标准
+
+- [ ] 纯 C 工程可链接并完成基础能力调用
+- [ ] C++ 对外部 C API 的适配调用行为可控、无未定义行为
+
+## M2. Concept/Traits 体系增强与元信息 API
+
+### 工作清单
+
+- [ ] 扩展 concept 分层（category/representation/policy-capability）
+- [ ] 完善 `traits<T>` 元信息（`kind`、`rep_type`、limits、policy tags）
+- [ ] 提供检测类 API（可转换性/是否有损/错误模型能力）
+- [ ] 统一 `constexpr` 查询入口，减少分散 traits 访问
+- [ ] 增加编译期测试矩阵（`static_assert` 覆盖）
+
+### 验收标准
+
+- [ ] 上层模块仅依赖公开 concept/traits，不依赖 `details::*`
+- [ ] 元信息可支撑转换层与算法层的约束判定
+
+## M3. 显式转换层（任意策略组适用）
+
+### 工作清单
+
+- [ ] 设计统一接口族（建议）：`explicit_cast`、`try_cast`、`checked_cast`
+- [ ] 支持任意策略组组合，不绑定特定策略实现
+- [ ] 风险可见化（截断/溢出/精度损失）并可程序化读取
+- [ ] 定义失败语义（错误码或 expected 风格，按策略可配置）
+- [ ] 建立转换矩阵测试（同类/跨类/跨策略组）
+
+### 验收标准
+
+- [ ] 所有跨类高风险转换必须走显式 API
+- [ ] 风险信息可在编译期或运行期被确定性获取
+
+## M4. 算法层（以 max/min 为起点）
+
+### 工作清单
+
+- [ ] 实现 `max`/`min`，并预留 `clamp`/`compare` 扩展位
+- [ ] 算法统一依赖 M2+M3 的公开接口，不绕过转换层
+- [ ] 支持同类与受约束的异类输入
+- [ ] 在可行范围保持 `constexpr`/`noexcept` 特性
+- [ ] 增加边界测试（极值、NaN、有符号/无符号混合）
+
+### 验收标准
+
+- [ ] 算法行为与策略约束一致
+- [ ] 风险路径始终显式、可审计
+
+## 建议推进顺序
+
+1. M2（先夯实约束与元信息基础）
+2. M1（建立跨语言边界）
+3. M3（收敛转换风险）
+4. M4（复用基础能力实现算法）
+
+## 总体完成跟踪
+
+- [ ] M1 完成
+- [ ] M2 完成
+- [ ] M3 完成
+- [ ] M4 完成

.github/copilot-instructions.md

@@ -14,7 +14,7 @@
 
 ## 正在进行中的计划
 
-- 当前计划目录：`../.github/prompts/`
+- 当前计划目录：`../.agents/docs/plans/`
 
 ## 说明
 

src/operations/dispatcher.cppm

@@ -15,36 +15,31 @@ import mcpplibs.primitives.underlying;
 
 export namespace mcpplibs::primitives::operations {
 
-template <typename T>
-concept primitive_instance = requires {
-  typename primitives::meta::traits<
-      std::remove_cvref_t<T>>::value_type;
-};
-
-template <operation OpTag, primitive_instance Lhs, primitive_instance Rhs,
+template <operation OpTag, meta::primitive_type Lhs,
+          meta::primitive_type Rhs,
           typename ErrorPayload = policy::error::kind>
 struct dispatcher_meta {
   using lhs_primitive = std::remove_cvref_t<Lhs>;
   using rhs_primitive = std::remove_cvref_t<Rhs>;
 
-  using lhs_traits = primitives::meta::traits<lhs_primitive>;
-  using rhs_traits = primitives::meta::traits<rhs_primitive>;
+  using lhs_traits = meta::traits<lhs_primitive>;
+  using rhs_traits = meta::traits<rhs_primitive>;
 
   using lhs_value_type = lhs_traits::value_type;
   using rhs_value_type = rhs_traits::value_type;
 
   using lhs_rep = underlying::traits<lhs_value_type>::rep_type;
   using rhs_rep = underlying::traits<rhs_value_type>::rep_type;
 
-  using lhs_type_policy = typename lhs_traits::type_policy;
-  using lhs_value_policy = typename lhs_traits::value_policy;
-  using lhs_error_policy = typename lhs_traits::error_policy;
-  using lhs_concurrency_policy = typename lhs_traits::concurrency_policy;
+  using lhs_type_policy = lhs_traits::type_policy;
+  using lhs_value_policy = lhs_traits::value_policy;
+  using lhs_error_policy = lhs_traits::error_policy;
+  using lhs_concurrency_policy = lhs_traits::concurrency_policy;
 
-  using rhs_type_policy = typename rhs_traits::type_policy;
-  using rhs_value_policy = typename rhs_traits::value_policy;
-  using rhs_error_policy = typename rhs_traits::error_policy;
-  using rhs_concurrency_policy = typename rhs_traits::concurrency_policy;
+  using rhs_type_policy = rhs_traits::type_policy;
+  using rhs_value_policy = rhs_traits::value_policy;
+  using rhs_error_policy = rhs_traits::error_policy;
+  using rhs_concurrency_policy = rhs_traits::concurrency_policy;
 
   static constexpr bool policy_group_consistent =
       std::is_same_v<lhs_type_policy, rhs_type_policy> &&
@@ -85,15 +80,17 @@ struct dispatcher_meta {
                                       ErrorPayload>;
 };
 
-template <operation OpTag, primitive_instance Lhs, primitive_instance Rhs,
+template <operation OpTag, primitives::meta::primitive_type Lhs,
+          primitives::meta::primitive_type Rhs,
           typename ErrorPayload = policy::error::kind>
 using dispatch_result_t = std::expected<
     typename dispatcher_meta<OpTag, Lhs, Rhs, ErrorPayload>::common_rep,
     ErrorPayload>;
 
 // Dispatcher pipeline: compile-time negotiation plus runtime chain
 // (concurrency -> value -> error) through selected policy handlers.
-template <operation OpTag, primitive_instance Lhs, primitive_instance Rhs,
+template <operation OpTag, primitives::meta::primitive_type Lhs,
+          primitives::meta::primitive_type Rhs,
           typename ErrorPayload = policy::error::kind>
 constexpr auto dispatch(Lhs const &lhs, Rhs const &rhs)
     -> dispatch_result_t<OpTag, Lhs, Rhs, ErrorPayload> {

src/operations/invoker.cppm

@@ -17,9 +17,8 @@ import mcpplibs.primitives.policy.handler;
 import mcpplibs.primitives.policy.impl;
 import mcpplibs.primitives.policy.traits;
 
-export namespace mcpplibs::primitives::operations::runtime {
 
-namespace details {
+namespace mcpplibs::primitives::operations::runtime::details {
 
 template <typename CommonRep>
 constexpr auto make_error(policy::error::kind kind, char const *reason,
@@ -781,18 +780,22 @@ constexpr auto make_div_zero(char const *reason)
   return make_error<CommonRep>(policy::error::kind::divide_by_zero, reason);
 }
 
-constexpr auto apply_runtime_fence(bool enabled,
-                                   std::memory_order order) noexcept -> void {
+constexpr auto apply_runtime_fence(const bool enabled,
+                                   const std::memory_order order) noexcept -> void {
   if (!enabled) {
     return;
   }
 
-  if (!std::is_constant_evaluated()) {
+  if !consteval {
     std::atomic_thread_fence(order);
   }
 }
 
-} // namespace details
+} // namespace mcpplibs::primitives::operations::runtime::details
+
+
+
+export namespace mcpplibs::primitives::operations::runtime {
 
 template <operation OpTag, policy::value_policy ValuePolicy, typename CommonRep>
 struct op_binding {