Skip to main content

aios_spec/
trace.rs

1//! 确定性 Trace — "how we prove correctness"
2//!
3//! Golden Trace 是 DiPECS 的确定性保证机制:
4//! 在相同输入序列下, 系统的脱敏输出和策略决策必须一致。
5
6use serde::{Deserialize, Serialize};
7
8use crate::event::{RawEvent, SourceTier};
9use crate::intent::IntentBatch;
10use crate::SanitizedEvent;
11
12fn default_source_tiers() -> Vec<SourceTier> {
13    Vec::new()
14}
15
16/// 一条 Golden Trace
17///
18/// 记录特定时间窗口内:
19/// 1. 输入序列 (RawEvent)
20/// 2. 期望的脱敏输出 (SanitizedEvent)
21/// 3. 期望的 LLM 返回 (IntentBatch)
22/// 4. 期望的执行动作 (ExecutedAction)
23///
24/// Golden Trace 文件存储在 `data/traces/` 目录下。
25/// 超过 1MB 的 trace 文件使用 Git LFS 托管。
26#[derive(Debug, Clone, Serialize, Deserialize)]
27pub struct GoldenTrace {
28    /// Trace 唯一 ID
29    pub trace_id: String,
30    /// 窗口起始时间 (epoch ms)
31    pub window_start_ms: i64,
32    /// 窗口结束时间 (epoch ms)
33    pub window_end_ms: i64,
34    /// 原始输入事件序列
35    pub raw_events: Vec<RawEvent>,
36    /// 期望的脱敏输出
37    pub expected_sanitized: Vec<SanitizedEvent>,
38    /// 期望的云端返回
39    pub expected_intents: IntentBatch,
40    /// 期望的本地执行动作
41    pub expected_actions: Vec<ExecutedAction>,
42    /// Per-event source tier, parallel to `raw_events`.
43    /// Empty or missing entries are handled at the consumption site
44    /// (trace_engine falls back to `SourceTier::PublicApi`).
45    #[serde(default = "default_source_tiers")]
46    pub source_tiers: Vec<SourceTier>,
47}
48
49/// 已执行的动作记录
50#[derive(Debug, Clone, Serialize, Deserialize)]
51pub struct ExecutedAction {
52    /// 动作类型
53    pub action_type: String,
54    /// 目标标识
55    pub target: Option<String>,
56    /// 执行时间 (epoch ms)
57    pub executed_at_ms: i64,
58    /// 执行是否成功
59    pub success: bool,
60    /// 失败原因 (如有)
61    pub error_reason: Option<String>,
62}
63
64/// 回放验证结果
65#[derive(Debug, Clone, Serialize, Deserialize)]
66pub struct ReplayResult {
67    /// 对应的 trace ID
68    pub trace_id: String,
69    /// 脱敏输出是否完全一致
70    pub sanitization_match: bool,
71    /// 不一致的 SanitizedEvent 索引
72    pub sanitization_divergences: Vec<usize>,
73    /// 策略决策是否完全一致
74    pub policy_match: bool,
75    /// 不一致的策略决策描述
76    pub policy_divergences: Vec<String>,
77    /// 执行结果是否完全一致
78    pub execution_match: bool,
79    /// 不一致的 ExecutedAction 索引
80    pub execution_divergences: Vec<usize>,
81}
82
83impl ReplayResult {
84    /// True iff sanitize + policy + execute all matched. The single boolean
85    /// that golden tests should pin against.
86    pub fn all_match(&self) -> bool {
87        self.sanitization_match && self.policy_match && self.execution_match
88    }
89}