Skip to main content

aios_core/
trace_engine.rs

1//! Trace 引擎 — 确定性回放验证
2//!
3//! 记录 `GoldenTrace` 并在回放时验证脱敏 / 策略 / 执行的确定性。
4//!
5//! 设计取舍:
6//! - 脱敏校验完全在 `aios-core` 内完成 (sanitizer 是 `PrivacyAirGap` 的
7//!   trait 对象),所以 `validate_sanitization` 不需要外部依赖。
8//! - 策略与执行的"实际值"必须由调用方驱动 (`aios-cli` 或 daemon 已经
9//!   持有 router/policy/executor),否则 `aios-core` 就要反向依赖
10//!   `aios-agent`。`TraceValidator::validate` 因此接收调用方已经计算好的
11//!   `actual_intents` 与 `actual_executed`,引擎只负责按"语义"逐条比对
12//!   并填出 `ReplayResult`。
13//!
14//! 语义比对刻意忽略易变字段 (uuids、wall-clock 时间),所以回放只验证
15//! pipeline 的可观测结果,不验证 token-by-token 的字节一致。如果想锁
16//! 字节一致,请用 `ReplaySummary.audit_hash`。
17
18use aios_spec::traits::{PrivacySanitizer, TraceValidator};
19use aios_spec::{
20    ExecutedAction, GoldenTrace, Intent, IntentBatch, ReplayResult, SanitizedEvent, SourceTier,
21    SuggestedAction,
22};
23
24/// 默认 Trace 引擎
25pub struct DefaultTraceEngine {
26    sanitizer: Box<dyn PrivacySanitizer + Send + Sync>,
27}
28
29impl DefaultTraceEngine {
30    pub fn new(sanitizer: impl PrivacySanitizer + Send + Sync + 'static) -> Self {
31        Self {
32            sanitizer: Box::new(sanitizer),
33        }
34    }
35
36    /// 仅校验脱敏。`policy_match` 与 `execution_match` 显式置为 `false`,
37    /// 且对应的 divergence 列表为空 —— 含义是"这一层未被检查",而不是
38    /// "检查过且失败"。两层语义分离:
39    ///
40    /// - match flag 回答"该层是否通过校验"。
41    /// - divergence 列表回答"如果失败了,是哪里失败"。
42    ///
43    /// 调用方通过 `result.all_match()` 自然区分;想做端到端校验请改用
44    /// [`TraceValidator::validate`],它会把三层都填出来。
45    pub fn validate_sanitization(&self, golden: &GoldenTrace) -> ReplayResult {
46        let sanitization_divergences = self.sanitization_divergences(golden);
47        ReplayResult {
48            trace_id: golden.trace_id.clone(),
49            sanitization_match: sanitization_divergences.is_empty(),
50            sanitization_divergences,
51            policy_match: false,
52            policy_divergences: vec![],
53            execution_match: false,
54            execution_divergences: vec![],
55        }
56    }
57
58    fn sanitization_divergences(&self, golden: &GoldenTrace) -> Vec<usize> {
59        let default_tier = SourceTier::PublicApi;
60        let tiers = golden
61            .source_tiers
62            .iter()
63            .chain(std::iter::repeat(&default_tier));
64
65        let actual_sanitized: Vec<SanitizedEvent> = golden
66            .raw_events
67            .iter()
68            .zip(tiers)
69            .map(|(raw, tier)| self.sanitizer.sanitize_with_tier(raw.clone(), *tier))
70            .collect();
71
72        let mut divergences = Vec::new();
73        for (i, (actual, expected)) in actual_sanitized
74            .iter()
75            .zip(golden.expected_sanitized.iter())
76            .enumerate()
77        {
78            if !sanitized_eq(actual, expected) {
79                divergences.push(i);
80            }
81        }
82        // 长度不一致时,把多余/缺失的索引也算进去。
83        let actual_len = actual_sanitized.len();
84        let expected_len = golden.expected_sanitized.len();
85        for i in actual_len.min(expected_len)..actual_len.max(expected_len) {
86            divergences.push(i);
87        }
88        divergences
89    }
90}
91
92impl TraceValidator for DefaultTraceEngine {
93    fn validate(
94        &self,
95        golden: &GoldenTrace,
96        actual_intents: &IntentBatch,
97        actual_executed: &[ExecutedAction],
98    ) -> ReplayResult {
99        let sanitization_divergences = self.sanitization_divergences(golden);
100        let policy_divergences = intent_divergences(&golden.expected_intents, actual_intents);
101        let execution_divergences =
102            execution_divergences(&golden.expected_actions, actual_executed);
103
104        ReplayResult {
105            trace_id: golden.trace_id.clone(),
106            sanitization_match: sanitization_divergences.is_empty(),
107            sanitization_divergences,
108            policy_match: policy_divergences.is_empty(),
109            policy_divergences,
110            execution_match: execution_divergences.is_empty(),
111            execution_divergences,
112        }
113    }
114}
115
116// ============================================================
117// 语义比较 — 忽略易变字段
118// ============================================================
119
120/// 比较两个 SanitizedEvent 的语义内容是否一致。
121///
122/// event_id 和 timestamp_ms 不在比较范围内 (它们因生成时间不同而变化)。
123fn sanitized_eq(a: &SanitizedEvent, b: &SanitizedEvent) -> bool {
124    a.event_type == b.event_type
125        && a.source_tier == b.source_tier
126        && a.app_package == b.app_package
127        && a.uid == b.uid
128}
129
130/// 比较两个 IntentBatch 的语义内容:window_id / generated_at_ms / intent_id
131/// 因为是 uuid/时间戳被刻意忽略。其它所有字段(包括 `rationale_tags`)都
132/// 参与比较。
133fn intent_divergences(expected: &IntentBatch, actual: &IntentBatch) -> Vec<String> {
134    let mut divergences = Vec::new();
135
136    if expected.model != actual.model {
137        divergences.push(format!(
138            "model mismatch: expected={:?} actual={:?}",
139            expected.model, actual.model
140        ));
141    }
142    if expected.intents.len() != actual.intents.len() {
143        divergences.push(format!(
144            "intent count mismatch: expected={} actual={}",
145            expected.intents.len(),
146            actual.intents.len()
147        ));
148        // 长度不同时继续按最小公共前缀逐条比对,便于定位首个差异。
149    }
150    let pairs = expected
151        .intents
152        .iter()
153        .zip(actual.intents.iter())
154        .enumerate();
155    for (i, (e, a)) in pairs {
156        if let Some(reason) = intent_diff(e, a) {
157            divergences.push(format!("intent[{i}]: {reason}"));
158        }
159    }
160    divergences
161}
162
163fn intent_diff(expected: &Intent, actual: &Intent) -> Option<String> {
164    if expected.intent_type != actual.intent_type {
165        return Some(format!(
166            "intent_type: expected={:?} actual={:?}",
167            expected.intent_type, actual.intent_type
168        ));
169    }
170    if expected.risk_level != actual.risk_level {
171        return Some(format!(
172            "risk_level: expected={:?} actual={:?}",
173            expected.risk_level, actual.risk_level
174        ));
175    }
176    if (expected.confidence - actual.confidence).abs() > f32::EPSILON {
177        return Some(format!(
178            "confidence: expected={} actual={}",
179            expected.confidence, actual.confidence
180        ));
181    }
182    if expected.rationale_tags != actual.rationale_tags {
183        return Some(format!(
184            "rationale_tags: expected={:?} actual={:?}",
185            expected.rationale_tags, actual.rationale_tags
186        ));
187    }
188    if expected.suggested_actions.len() != actual.suggested_actions.len() {
189        return Some(format!(
190            "suggested_actions count: expected={} actual={}",
191            expected.suggested_actions.len(),
192            actual.suggested_actions.len()
193        ));
194    }
195    for (j, (e_act, a_act)) in expected
196        .suggested_actions
197        .iter()
198        .zip(actual.suggested_actions.iter())
199        .enumerate()
200    {
201        if !suggested_eq(e_act, a_act) {
202            return Some(format!(
203                "suggested_actions[{j}]: expected={:?} actual={:?}",
204                e_act, a_act
205            ));
206        }
207    }
208    None
209}
210
211fn suggested_eq(a: &SuggestedAction, b: &SuggestedAction) -> bool {
212    a.action_type == b.action_type && a.target == b.target && a.urgency == b.urgency
213}
214
215fn execution_divergences(expected: &[ExecutedAction], actual: &[ExecutedAction]) -> Vec<usize> {
216    let mut divergences = Vec::new();
217    for (i, (e, a)) in expected.iter().zip(actual.iter()).enumerate() {
218        if !executed_eq(e, a) {
219            divergences.push(i);
220        }
221    }
222    // 长度差异也记入索引。
223    let actual_len = actual.len();
224    let expected_len = expected.len();
225    for i in actual_len.min(expected_len)..actual_len.max(expected_len) {
226        divergences.push(i);
227    }
228    divergences
229}
230
231/// 比较两个 ExecutedAction:忽略 executed_at_ms。
232fn executed_eq(a: &ExecutedAction, b: &ExecutedAction) -> bool {
233    a.action_type == b.action_type
234        && a.target == b.target
235        && a.success == b.success
236        && a.error_reason == b.error_reason
237}