futu_auth/limits/

types.rs

//! Split from limits.rs: types.
//!
//! pub items: Limits,CheckCtx,LimitReason,LimitOutcome,ValueRejectReason,market_to_currency,validate_order_value.

use std::collections::HashSet;

use serde::{Deserialize, Serialize};

/// 限额配置（与 KeyRecord 字段平级，独立出来便于传递）
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Limits {
    pub allowed_markets: Option<HashSet<String>>,
    pub allowed_symbols: Option<HashSet<String>>,
    pub max_order_value: Option<f64>,
    pub max_daily_value: Option<f64>,
    pub hours_window: Option<String>,
    /// 每分钟下单次数上限（滑动窗口，None 表示不限）。挡 spray-and-pray
    /// 类攻击：即使每单小于 max_order_value、日累计也够，也限制速率。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_orders_per_minute: Option<u32>,
    /// 允许的交易方向白名单：例如 `["SELL"]` = 只让平仓 bot 卖；
    /// None / 空集 → 不限。大小写敏感，用 `"BUY"` / `"SELL"` / `"SELL_SHORT"` / `"BUY_BACK"`。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub allowed_trd_sides: Option<HashSet<String>>,
    /// v1.4.35 加（external reviewer 回归报告建议 1）：**per-key acc_id 白名单**
    ///
    /// 语义：该 key 只能对这些 acc_id 发 trade / unlock / query 操作；超出
    /// 列表的 acc_id 直接被 auth 层拒（403）。None / 空集 → 不限（向后兼容老 key）。
    ///
    /// **定位**：operational safety（防 agent bug / LLM 幻觉 / key 泄露后爆炸半径）。
    /// **不等同** financial isolation —— 后者需要多 union card（L4，见 CLAUDE.md 隔离层级）。
    /// 对**纯现金策略**用户，L2 实质上等同财务隔离（没借钱就没传导）。
    ///
    /// 典型用法：
    /// ```text
    /// futucli gen-key --id bot-A --scopes trade:real,acc:read --allowed-acc-ids 10001,10002
    /// futucli gen-key --id bot-B --scopes trade:real,acc:read --allowed-acc-ids 10003
    /// ```
    /// bot-A 只能动 10001/10002，bot-B 只能动 10003，互不影响。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub allowed_acc_ids: Option<HashSet<u64>>,
    /// v1.4.103 (B10): per-key card_num 白名单 (string format).
    ///
    /// daemon 启动后通过 GetAccList resolve → 合并进 `allowed_acc_ids`. 详见
    /// [`KeyRecord::allowed_card_nums`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub allowed_card_nums: Option<Vec<String>>,
}

/// Borrowed view of the effective per-key limit policy.
///
/// Runtime checks accept this trait so a [`crate::KeyRecord`] can expose its
/// configured sets directly instead of allocating an owned [`Limits`] clone on
/// every authenticated request. The owned type remains part of the public API
/// for configuration and compatibility callers.
pub trait LimitPolicy {
    fn allowed_markets(&self) -> Option<&HashSet<String>>;
    fn allowed_symbols(&self) -> Option<&HashSet<String>>;
    fn max_order_value(&self) -> Option<f64>;
    fn max_daily_value(&self) -> Option<f64>;
    fn hours_window(&self) -> Option<&str>;
    fn max_orders_per_minute(&self) -> Option<u32>;
    fn allowed_trd_sides(&self) -> Option<&HashSet<String>>;
    fn allowed_acc_ids(&self) -> Option<&HashSet<u64>>;
    fn allowed_card_nums(&self) -> Option<&[String]>;
}

impl LimitPolicy for Limits {
    fn allowed_markets(&self) -> Option<&HashSet<String>> {
        self.allowed_markets.as_ref()
    }

    fn allowed_symbols(&self) -> Option<&HashSet<String>> {
        self.allowed_symbols.as_ref()
    }

    fn max_order_value(&self) -> Option<f64> {
        self.max_order_value
    }

    fn max_daily_value(&self) -> Option<f64> {
        self.max_daily_value
    }

    fn hours_window(&self) -> Option<&str> {
        self.hours_window.as_deref()
    }

    fn max_orders_per_minute(&self) -> Option<u32> {
        self.max_orders_per_minute
    }

    fn allowed_trd_sides(&self) -> Option<&HashSet<String>> {
        self.allowed_trd_sides.as_ref()
    }

    fn allowed_acc_ids(&self) -> Option<&HashSet<u64>> {
        self.allowed_acc_ids.as_ref()
    }

    fn allowed_card_nums(&self) -> Option<&[String]> {
        self.allowed_card_nums.as_deref()
    }
}

/// 限额检查上下文：一次下单的 market/symbol/金额/方向
#[derive(Debug, Clone, Default)]
pub struct CheckCtx {
    /// "HK" / "US" / "CN" / "HKCC" 等
    pub market: String,
    /// "HK.00700" 格式（market + code）；**空串** 表示调用方无法推导 symbol
    /// （改单 / 撤单路径），此时 symbol 白名单检查被跳过（但 market 仍会被校验）。
    pub symbol: String,
    /// qty × price（本币）；None 表示无法计算（如 MARKET 单），跳过金额检查
    pub order_value: Option<f64>,
    /// 交易方向字符串（`"BUY"` / `"SELL"` / ...）；None 表示无需方向校验
    /// （改单 / 撤单路径）
    pub trd_side: Option<String>,
    /// v1.4.35：被操作的账户 ID；None 表示此请求不涉及特定账户（全局请求
    /// 如 subscribe / quote，跳过 acc_id 白名单检查）。
    pub acc_id: Option<u64>,
    /// v1.4.106 codex 0538 F2 (P2): typed marker — 此 mutation 不产生
    /// 新 exposure delta（撤单 / 失效 / 生效 / 删除老单）。
    ///
    /// **语义**：true = 改 daemon 状态但不动 risk exposure（不跑 daily
    /// counter, 但仍跑 acc_id / market / rate / hours 白名单）。
    /// false = 真有 exposure delta（PlaceOrder, ModifyOrder Normal）→
    /// 必须给 order_value 让 daily counter 累加.
    ///
    /// 区分 ModifyOrder 5 种 op:
    ///
    /// | modify_order_op | 含义 | mutation_no_exposure | order_value |
    /// |---|---|---|---|
    /// | 1 (Normal) | 改价 / 改量 → 新 exposure | **false** | Some(qty*price) |
    /// | 2 (Cancel) | 撤单 → 减 exposure | true | None |
    /// | 3 (Disable) | 失效 | true | None |
    /// | 4 (Enable) | 生效（之前 Disable）| true | None (cap 难算) |
    /// | 5 (Delete) | 删除老单 | true | None |
    ///
    /// **保守语义**：Enable 理论可重新激活老单产生 exposure, 但不知 qty/price
    /// 上下文（仅靠 order_id），无法算 order_value → 标 mutation_no_exposure
    /// = true（跳 daily counter）；rate-window 仍计数挡 spray attack。
    ///
    /// **默认 false**: 所有 PlaceOrder / 已知 exposure 路径默认 false（保守）。
    pub mutation_no_exposure: bool,
    /// v1.4.106 codex 0538 F4 (P3): 订单币种 (`HKD` / `USD` / `CNY` / `JPY`
    /// / `SGD` / `AUD` / `MYR` / `CAD` 等)
    ///
    /// **None** = 让 auth 层从 [`Self::market`] 派生；market 也无法派生时才进入
    /// legacy 单桶模式 (counter 全合并到 `_default_` key, 与 v1.4.105 行为兼容);
    ///
    /// **Some(ccy)** = per-currency 桶 (HKD / USD / ... 各自独立 daily counter,
    /// USD 单不消耗 HKD 配额, 防 cross-currency dilution).
    ///
    /// `Limits::max_daily_value` cap 解释成**每个 currency 桶独立 cap**.
    ///
    /// 防御性语义：调用方可提供，但 daily bucket 选择会优先使用
    /// [`market_to_currency`] 的派生值，避免跨 surface 误传 currency 导致额度记错桶。
    pub currency: Option<String>,
}

impl CheckCtx {
    /// Return the daily-limit currency bucket for this request.
    ///
    /// Known markets are authoritative because all current order-write surfaces
    /// already carry a market, while some legacy/MCP callers still leave
    /// `currency=None`. If both are present but conflict, use the market-derived
    /// bucket and log the mismatch for diagnostics.
    pub fn daily_currency(&self) -> Option<String> {
        let derived = market_to_currency(self.market.as_str());
        match (derived, self.currency.as_deref()) {
            (Some(market_currency), Some(caller_currency))
                if !caller_currency.eq_ignore_ascii_case(market_currency) =>
            {
                tracing::warn!(
                    market = %self.market,
                    caller_currency,
                    derived_currency = market_currency,
                    "CheckCtx currency mismatch; using market-derived daily limit bucket"
                );
                Some(market_currency.to_string())
            }
            (Some(market_currency), _) => Some(market_currency.to_string()),
            (None, Some(caller_currency)) => {
                let trimmed = caller_currency.trim();
                (!trimmed.is_empty()).then(|| trimmed.to_ascii_uppercase())
            }
            (None, None) => None,
        }
    }
}

/// v1.4.106 codex 0538 F4 (P3): trd market → currency 推导.
///
/// 用于派生 [`CheckCtx::currency`]. 各市场按 base trading currency:
///
/// | market | currency |
/// |---|---|
/// | HK / HKCC | HKD |
/// | US | USD |
/// | CN | CNY |
/// | JP | JPY |
/// | SG | SGD |
/// | AU | AUD |
/// | MY | MYR |
/// | CA | CAD |
/// | 其他 (FUTURES / 未知) | None (合并到 default 桶) |
///
/// **注意**: HKCC (HK 沪港通) 实际多币种, 但 daily counter 视角统一 HKD —
/// 避免双桶碎片化. 真实多币种细分 (e.g. 沪港通买卖差价是 HKD 还是 CNY)
/// 应由 backend 业务层决定, daemon 限额引擎只挡 quota.
#[must_use]
pub fn market_to_currency(market: &str) -> Option<&'static str> {
    match market {
        "HK" | "HKCC" => Some("HKD"),
        "US" => Some("USD"),
        "CN" => Some("CNY"),
        "JP" => Some("JPY"),
        "SG" => Some("SGD"),
        "AU" => Some("AUD"),
        "MY" => Some("MYR"),
        "CA" => Some("CAD"),
        _ => None,
    }
}

/// **v1.4.106 codex 0542 F2 [P2 SECURITY]**: 限额拒绝原因 typed enum.
///
/// 三层语义视图同 reject 不同消费方:
///
/// | 视图 | 用途 | 是否含 PII / 敏感细节 |
/// |---|---|---|
/// | [`Self::public_message`] | client error body (REST 403/429 JSON, gRPC Status.message) | **不含** — 只说 "rejected by <category>" |
/// | [`Self::audit_message`]  | audit log + tracing (内部 ops 用) | 含 — `daily 27000.00 > 25000.00` 等数值 |
/// | [`Self::metric_label`]   | Prometheus `reason` label (固定桶) | **不含** — 固定 8 字串集合 |
///
/// **设计动机** (v1.4.105 之前):
///
/// 老代码 `LimitOutcome::*Reject(String)` 把 `format!("daily value 27000.00 > 25000.00 (current=18000.00 + order=9000.00)")`
/// 同字符串既给 client (HTTP body) 又给 audit log 又给 prometheus reason
/// (走 [`crate::metrics::classify_limit_reason`] 字符串前缀分桶). 三个 leak:
///
/// 1. **client 看到 user 内部数值** — 攻击者撞 daily cap 时能精确推出 cap
///    threshold 与当前累计 (cap=25000, current=18000 → 还能下 7000).
/// 2. **prometheus reason label 字符串前缀分桶** — 任何 reason format 漂移
///    (e.g. 加 ", retry after 60s") 落到 `other` 桶, dashboard 静默断流.
///    维护需 "新增 reason category 时同步改 classify_limit_reason match
///    arm" — 易漂.
/// 3. **audit log 与 client message 无法独立演进** — 想给 audit 加更细节
///    时, 等同于给 client error body 也加, surface mismatch.
///
/// **F2 修法**: typed enum + 3 个 method, 各自只 emit 自己 surface 需要的
/// 信息. caller 用 `match` 编译期穷举确保不漏 surface, [`crate::metrics::
/// classify_limit_reason`] 仍保留 (作向后兼容兜底字符串路径), 但新代码走
/// `LimitReason::metric_label()` 拿固定桶名.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum LimitReason {
    /// per-key acc_id 白名单拒 (403). `id` = 实际请求 acc_id, `allowed_count`
    /// = 配置白名单 entry 数 (audit 用; client surface 不展示).
    AccIdWhitelist { id: u64, allowed_count: usize },
    /// 市场白名单拒 (403). `requested` = 请求 market (e.g. "US"),
    /// `allowed_count` = 配置 set size.
    MarketWhitelist {
        requested: String,
        allowed_count: usize,
    },
    /// 品种白名单拒 (403). `requested` = 请求 symbol (e.g. "HK.09988"),
    /// 不返 allowed list (太长, 也 leak 内部允许品种).
    SymbolWhitelist { requested: String },
    /// 交易方向白名单拒 (403). `requested` = 请求 side ("BUY" / "SELL" /
    /// "SELL_SHORT" / "BUY_BACK"), `allowed_count` = 配置 set size.
    TrdSideWhitelist {
        requested: String,
        allowed_count: usize,
    },
    /// 时间窗外拒 (429 — 用户之后再试). `spec` = 配置 (e.g. "09:30-16:00"),
    /// `now_hhmm` = 当前 local time (e.g. "08:15").
    HoursOutsideWindow { spec: String, now_hhmm: String },
    /// 时间窗 spec 解析失败 (429 — 配置 bug). `spec` = 原 string, `err` = 解析错.
    HoursInvalidSpec { spec: String, err: String },
    /// 单笔上限超 (403). `value` = 请求金额, `cap` = 配置 per-order cap.
    PerOrderCap { value: f64, cap: f64 },
    /// per-minute 速率超 (429). `recent` = 60s 内已下单数, `cap` = 配置 cap.
    RateLimit { recent: u32, cap: u32 },
    /// 日累计超 (429). `next` = 累加后 total, `cap` = 配置 daily cap, `current`
    /// = 累加前 total, `add` = 本次金额.
    DailyCap {
        next: f64,
        cap: f64,
        current: f64,
        add: f64,
    },
}

impl LimitReason {
    /// **client surface** (REST 403/429 JSON / gRPC Status.message): 只说
    /// "rejected by <category>" + 极简 hint, **不含** cap / threshold / current
    /// 等数值 (反 enumeration / probing).
    #[must_use]
    pub fn public_message(&self) -> String {
        match self {
            LimitReason::AccIdWhitelist { .. } => "acc_id not in allowed list".to_string(),
            LimitReason::MarketWhitelist { .. } => "market not in allowed list".to_string(),
            LimitReason::SymbolWhitelist { .. } => "symbol not in allowed list".to_string(),
            LimitReason::TrdSideWhitelist { .. } => "trd_side not in allowed list".to_string(),
            LimitReason::HoursOutsideWindow { .. } => "outside trading hours window".to_string(),
            LimitReason::HoursInvalidSpec { .. } => {
                "trading hours window misconfigured".to_string()
            }
            LimitReason::PerOrderCap { .. } => "order value exceeds per-order cap".to_string(),
            LimitReason::RateLimit { .. } => "rate limit exceeded".to_string(),
            LimitReason::DailyCap { .. } => "daily value cap exceeded".to_string(),
        }
    }

    /// **audit / log surface** (内部 ops, full detail), 含数值 + threshold.
    ///
    /// 与 v1.4.105 之前 `Reject(String)` 字符串内容兼容 — 保留前缀 (e.g.
    /// `"rate limit exceeded:"`) 让 [`crate::metrics::classify_limit_reason`]
    /// 字符串桶继续命中 (向后兼容已有 dashboard).
    #[must_use]
    pub fn audit_message(&self) -> String {
        match self {
            LimitReason::AccIdWhitelist { id, allowed_count } => {
                format!("acc_id {id} not in allowed list ({allowed_count} entries)")
            }
            LimitReason::MarketWhitelist {
                requested,
                allowed_count,
            } => {
                format!("market {requested:?} not in allowed list ({allowed_count} entries)")
            }
            LimitReason::SymbolWhitelist { requested } => {
                format!("symbol {requested:?} not in allowed list")
            }
            LimitReason::TrdSideWhitelist {
                requested,
                allowed_count,
            } => {
                format!("trd_side {requested:?} not in allowed list ({allowed_count} entries)")
            }
            LimitReason::HoursOutsideWindow { spec, now_hhmm } => {
                format!("outside hours window {spec} (now={now_hhmm})")
            }
            LimitReason::HoursInvalidSpec { spec, err } => {
                format!("invalid hours_window {spec:?}: {err}")
            }
            LimitReason::PerOrderCap { value, cap } => {
                format!("order value {value:.2} exceeds per-order cap {cap:.2}")
            }
            LimitReason::RateLimit { recent, cap } => {
                format!("rate limit exceeded: {recent} orders in the last 60s (cap {cap})")
            }
            LimitReason::DailyCap {
                next,
                cap,
                current,
                add,
            } => format!(
                "daily value cap exceeded: {next:.2} > {cap:.2} (current={current:.2} + order={add:.2})"
            ),
        }
    }

    /// **prometheus surface**: 固定 8 字串集合, 任何漂移 (audit_message format
    /// 改) 都不影响 dashboard. 与 [`crate::metrics::classify_limit_reason`] 字符串
    /// 前缀分桶**保持 1-1 对应**, 但典型化为编译期穷举.
    #[must_use]
    pub fn metric_label(&self) -> &'static str {
        match self {
            LimitReason::AccIdWhitelist { .. } => "acc_id",
            LimitReason::MarketWhitelist { .. } => "market",
            LimitReason::SymbolWhitelist { .. } => "symbol",
            LimitReason::TrdSideWhitelist { .. } => "side",
            LimitReason::HoursOutsideWindow { .. } | LimitReason::HoursInvalidSpec { .. } => {
                "hours"
            }
            LimitReason::PerOrderCap { .. } => "per_order",
            LimitReason::RateLimit { .. } => "rate",
            LimitReason::DailyCap { .. } => "daily",
        }
    }

    /// HTTP status code: 429 (rate-like, retry) vs 403 (whitelist/value, don't retry).
    #[must_use]
    pub fn http_status_code(&self) -> u16 {
        match self {
            // throughput-like (rate / hours / daily) → 429
            LimitReason::HoursOutsideWindow { .. }
            | LimitReason::HoursInvalidSpec { .. }
            | LimitReason::RateLimit { .. }
            | LimitReason::DailyCap { .. } => 429,
            // whitelist / value → 403
            LimitReason::AccIdWhitelist { .. }
            | LimitReason::MarketWhitelist { .. }
            | LimitReason::SymbolWhitelist { .. }
            | LimitReason::TrdSideWhitelist { .. }
            | LimitReason::PerOrderCap { .. } => 403,
        }
    }
}

/// 限额检查结果
///
/// v1.4.36 Bug #1 扩展：拒绝类型区分 `Throughput` vs `Whitelist` vs `Value`，
/// 让 REST / gRPC middleware 能把不同类型映射到正确的 HTTP status：
///
/// - **Throughput**（速率 / 日累计 / 时间窗）→ HTTP 429 Too Many Requests
///   客户端按 rate-limit 语义 backoff 重试即可
/// - **Whitelist**（market / symbol / trd_side / acc_id 不在白名单）→ HTTP 403 Forbidden
///   客户端**不该重试**，是权限问题，需要改 key / 改请求参数
/// - **Value**（单笔上限超 / NaN / inf / 负数）→ HTTP 403 Forbidden
///   同 Whitelist，不该重试；需要拆单或换 key
///
/// **v1.4.106 codex 0542 F2 [P2 SECURITY]**: `*Reject(String)` variants 现承载
/// `audit_message()` (内部 full-detail). client surface 应通过新 [`LimitReason`]
/// 字段拿 `public_message()` (terse, no cap leak). 见 [`Self::reason_typed`].
///
/// 老代码用 `Reject(String)`，保留作向后兼容 —— 但新检查应返对应 `*Reject` 类型。
///
/// v1.4.106 codex 0538 F1 (P1 SECURITY): `ValueReject` 内部带结构化原因，
/// 让 fail-closed validation (NaN / inf / negative) 与 normal cap-exceeded
/// 区分；display 消息仍 backward-compat 字符串格式。
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum LimitOutcome {
    Allow,
    /// 速率 / 日累计 / 时间窗类拒绝（429 语义：客户端应 backoff 重试）.
    /// String = `LimitReason::audit_message()`.
    ThroughputReject(String),
    /// 白名单类拒绝（403 语义：权限问题，不该重试）.
    /// String = `LimitReason::audit_message()`.
    WhitelistReject(String),
    /// 金额上限拒绝（403 语义：不该重试；拆单或换 key）.
    /// String = `LimitReason::audit_message()`.
    ValueReject(String),
    /// **v1.4.106 codex 0542 F2**: typed reject — 推荐新代码用此 variant,
    /// caller 通过 `LimitReason::public_message()` / `audit_message()` /
    /// `metric_label()` 各自取所需视图. 与三个老 String variant 共存
    /// (新代码 emit `Typed`, 老代码 emit `*Reject(String)` 仍工作).
    Typed(LimitReason),
}

/// 金额拒绝的结构化原因（v1.4.106 codex 0538 F1 P1 SECURITY）
///
/// 区分 fail-closed validation (NaN / inf / negative) 与 normal cap exceed，
/// 便于 caller 决定是否 audit-log（fail-closed → 高优先级 audit）。display
/// 消息仍是 backward-compat 字符串。
///
/// **NaN / inf / negative 全归 fail-closed**：金融场景不允许这些值流过
/// 限额引擎 —— LLM agent / proto fuzz / unsanitized REST body 任一来源传
/// `f64::NAN` 都会让 `value > cap + EPSILON` 静默 false（NaN compare 总返
/// false），bypass per-order cap 与 daily counter；负数则把 daily counter
/// **倒减**让后续大单通过。三类全 fail-closed 拒。
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum ValueRejectReason {
    /// 单笔超过 max_order_value cap
    OverPerOrderCap,
    /// 日累计超过 max_daily_value cap
    OverDailyCap,
    /// order_value 为 NaN（fail-closed）
    NotANumber,
    /// order_value 为 +inf / -inf（fail-closed）
    Infinite,
    /// order_value 为负数（fail-closed —— 负数会倒减 daily counter）
    Negative,
}

impl ValueRejectReason {
    /// 是否为 fail-closed validation 拒绝（NaN / inf / negative）—— 高优先级 audit
    #[must_use]
    pub fn is_fail_closed(&self) -> bool {
        matches!(self, Self::NotANumber | Self::Infinite | Self::Negative)
    }
}

/// 校验 order_value 数值合法性（v1.4.106 codex 0538 F1 P1 SECURITY）
///
/// 防御 NaN / inf / negative 三类异常输入。所有走 limit 引擎的 order_value
/// **必须**先过这层，否则：
///
/// - **NaN**：`x > cap + EPSILON` 总 false → bypass 单笔 cap；
///   daily counter `total + NaN = NaN` → 后续 compare 全 false → 永远 allow.
/// - **+inf / -inf**：算术 saturate → daily counter inf → 任何后续 add 仍 inf
///   → reject 但 lose precision；负 inf 让 daily 立即变 -inf → 永远 allow.
/// - **negative**：daily total + (-100) = total - 100 → daily counter 倒退
///   → 让后续大单通过 cap.
///
/// 三类全 fail-closed (`Err(ValueRejectReason::*)`)。
pub fn validate_order_value(v: f64) -> Result<f64, ValueRejectReason> {
    if v.is_nan() {
        return Err(ValueRejectReason::NotANumber);
    }
    if v.is_infinite() {
        return Err(ValueRejectReason::Infinite);
    }
    if v < 0.0 {
        return Err(ValueRejectReason::Negative);
    }
    Ok(v)
}

impl LimitOutcome {
    /// 是否拒绝（`!is_allow` 等价于"拒绝"）
    #[must_use]
    pub fn is_allow(&self) -> bool {
        matches!(self, LimitOutcome::Allow)
    }

    /// 拒绝时的 reason 字符串（Allow 返 None）.
    ///
    /// **v1.4.106 codex 0542 F2 调整**: 现返 `Option<String>` (老
    /// `Option<&str>` 兼容性 break, 但所有内部 caller 用 `format!("{reason}")`
    /// 不受影响). 走 [`Self::public_message`] 取 client surface 安全形式.
    pub fn reason(&self) -> Option<String> {
        match self {
            LimitOutcome::Allow => None,
            LimitOutcome::ThroughputReject(s)
            | LimitOutcome::WhitelistReject(s)
            | LimitOutcome::ValueReject(s) => Some(s.clone()),
            LimitOutcome::Typed(r) => Some(r.audit_message()),
        }
    }

    /// **v1.4.106 codex 0542 F2**: typed reason (若 `Typed(r)` variant), 否则 None.
    #[must_use]
    pub fn reason_typed(&self) -> Option<&LimitReason> {
        match self {
            LimitOutcome::Typed(r) => Some(r),
            _ => None,
        }
    }

    /// **v1.4.106 codex 0542 F2**: client-surface terse message.
    pub fn public_message(&self) -> Option<String> {
        match self {
            LimitOutcome::Allow => None,
            LimitOutcome::ThroughputReject(s)
            | LimitOutcome::WhitelistReject(s)
            | LimitOutcome::ValueReject(s) => Some(s.clone()),
            LimitOutcome::Typed(r) => Some(r.public_message()),
        }
    }

    /// **v1.4.106 codex 0542 F2**: prometheus metric_label (8 固定桶) 若 typed.
    #[must_use]
    pub fn metric_label(&self) -> Option<&'static str> {
        match self {
            LimitOutcome::Typed(r) => Some(r.metric_label()),
            _ => None,
        }
    }

    /// 适合此拒绝类型的 HTTP 状态码（REST / gRPC middleware 用）
    ///
    /// - `Allow` → 200
    /// - `Throughput` / typed throughput → 429
    /// - `Whitelist` / `Value` / typed whitelist/value → 403
    #[must_use]
    pub fn http_status_code(&self) -> u16 {
        match self {
            LimitOutcome::Allow => 200,
            LimitOutcome::ThroughputReject(_) => 429,
            LimitOutcome::WhitelistReject(_) | LimitOutcome::ValueReject(_) => 403,
            LimitOutcome::Typed(r) => r.http_status_code(),
        }
    }
}