Skip to main content

aios_core/
action_lifecycle.rs

1//! Action Bus 生命周期状态机
2//!
3//! 唯一入口 `ActionLifecycle::run`。它把每个 `(intent, action)` 展开为一个
4//! `ActionProposal`,驱动其经过 schema 校验、策略裁决、adapter 执行,最终产出
5//! 恰好一条带终态的 `AuditRecord`。
6
7use std::collections::HashMap;
8
9use aios_spec::governance::{
10    ActionCoord, ActionOutcomeSummary, ActionProposal, ActionState, AuditRecord, EffectClass,
11    PolicyActionDecision, PolicyVerdict,
12};
13use aios_spec::intent::{
14    ActionType, CapabilityLevel, DecisionRoute, DenialReason, IntentBatch, RiskLevel,
15};
16use aios_spec::StructuredContext;
17use thiserror::Error;
18use tracing::debug;
19
20use crate::governance::{ActionAdapter, AuthorizedAction};
21use crate::policy_engine::PolicyEngine;
22
23/// 生命周期状态机内部错误。这些错误不会 panic,而是被记录为对应 `AuditRecord`
24/// 的 `Failed` 终态或 `RejectedInvalidSchema` 终态。
25#[derive(Debug, Clone, Error)]
26pub enum LifecycleError {
27    #[error("internal: missing policy decision for coord {0:?}")]
28    MissingPolicyDecision(ActionCoord),
29    #[error("schema violation: {0}")]
30    SchemaViolation(String),
31}
32
33/// Action Bus 治理状态机。
34///
35/// 内部持有 `PolicyEngine` 与 `ActionAdapter`,是 `AuthorizedAction` 的唯一构造点。
36pub struct ActionLifecycle<'a> {
37    policy: &'a PolicyEngine,
38    adapter: &'a dyn ActionAdapter,
39}
40
41impl<'a> ActionLifecycle<'a> {
42    pub fn new(policy: &'a PolicyEngine, adapter: &'a dyn ActionAdapter) -> Self {
43        Self { policy, adapter }
44    }
45
46    /// 暴露内部持有的 `PolicyEngine`,供调用方在 Policy-only 阶段直接做策略裁决。
47    pub fn policy(&self) -> &'a PolicyEngine {
48        self.policy
49    }
50
51    /// 处理一个窗口的意图批次,返回每条动作恰好一条终态审计记录。
52    ///
53    /// `window_ordinal` 由调用方(replay/daemon 驱动循环)显式传入,保证状态机
54    /// 本身无隐藏可变状态,且 replay 间坐标稳定。
55    pub fn run(
56        &self,
57        window_ordinal: u32,
58        batch: &IntentBatch,
59        route: DecisionRoute,
60        backend_error: Option<String>,
61        capability: &CapabilityLevel,
62        ctx: &StructuredContext,
63    ) -> Vec<AuditRecord> {
64        let policy_decisions = self
65            .policy
66            .evaluate_batch_with_context(batch, capability, ctx);
67        let decisions_by_coord: HashMap<(u32, u32), &PolicyActionDecision> = policy_decisions
68            .iter()
69            .map(|d| ((d.intent_ordinal, d.action_ordinal), d))
70            .collect();
71
72        let mut records = Vec::new();
73        let authorized_at_ms = batch.generated_at_ms;
74
75        for (intent_ordinal, intent) in batch.intents.iter().enumerate() {
76            let intent_ordinal = intent_ordinal as u32;
77            for (action_ordinal, suggested_action) in intent.suggested_actions.iter().enumerate() {
78                let action_ordinal = action_ordinal as u32;
79                let coord = ActionCoord {
80                    window_ordinal,
81                    intent_ordinal,
82                    action_ordinal,
83                };
84                let proposal = ActionProposal {
85                    intent_id: intent.intent_id.clone(),
86                    coord,
87                    action: suggested_action.clone(),
88                    effect: EffectClass::from_action_type(&suggested_action.action_type),
89                    proposed_at_ms: authorized_at_ms,
90                };
91
92                let mut record = AuditRecord::new(&proposal, route, ctx.summary.source_tier);
93
94                // Schema validation
95                if let Some(err) = validate_schema(&proposal, &intent.risk_level) {
96                    record.transition(ActionState::RejectedInvalidSchema);
97                    record.error = Some(err.to_string());
98                    record.backend_error = backend_error.clone();
99                    records.push(record);
100                    continue;
101                }
102                record.transition(ActionState::SchemaValidated);
103
104                // Policy verdict lookup
105                let decision = decisions_by_coord
106                    .get(&(intent_ordinal, action_ordinal))
107                    .copied()
108                    .ok_or(LifecycleError::MissingPolicyDecision(coord));
109
110                match decision {
111                    Ok(d) => match d.verdict {
112                        PolicyVerdict::Approved => {
113                            record.transition(ActionState::PolicyChecked);
114                            let authorized = AuthorizedAction::seal(&proposal, authorized_at_ms);
115                            record.transition(ActionState::Dispatched);
116                            match self.adapter.execute(&authorized) {
117                                Ok(outcome) => {
118                                    record.transition(ActionState::Succeeded);
119                                    record.outcome =
120                                        Some(ActionOutcomeSummary::from_outcome(&outcome));
121                                    record.backend_error = backend_error.clone();
122                                },
123                                Err(err) => {
124                                    record.transition(ActionState::Failed);
125                                    record.error = Some(err.to_string());
126                                    record.backend_error = backend_error.clone();
127                                },
128                            }
129                        },
130                        PolicyVerdict::Denied(reason) => {
131                            record.transition(ActionState::PolicyChecked);
132                            let terminal = denial_to_terminal(reason);
133                            record.transition(terminal);
134                            record.denial_reason = Some(reason);
135                            record.backend_error = backend_error.clone();
136                        },
137                    },
138                    Err(err) => {
139                        debug!(error = %err, "lifecycle internal error");
140                        record.transition(ActionState::Failed);
141                        record.error = Some(err.to_string());
142                        record.backend_error = backend_error.clone();
143                    },
144                }
145
146                records.push(record);
147            }
148        }
149
150        records
151    }
152}
153
154/// Schema 校验:缺失必需 target、非法 risk/effect 组合等。
155fn validate_schema(proposal: &ActionProposal, intent_risk: &RiskLevel) -> Option<LifecycleError> {
156    if proposal.action.action_type == ActionType::PreWarmProcess {
157        match proposal.action.target.as_deref() {
158            Some(t) if !t.is_empty() => {},
159            _ => {
160                return Some(LifecycleError::SchemaViolation(
161                    "PreWarmProcess requires a non-empty target".into(),
162                ));
163            },
164        }
165    }
166
167    // risk/effect 非法组合:PureRead 动作不应承载 High 风险意图。
168    if proposal.effect == EffectClass::PureRead && *intent_risk == RiskLevel::High {
169        return Some(LifecycleError::SchemaViolation(
170            "PureRead action cannot carry High risk intent".into(),
171        ));
172    }
173
174    None
175}
176
177/// 将 `DenialReason` 映射到终态。
178///
179/// Capability 相关拒绝独立为 `DeniedByCapability`,其余策略拒绝归
180/// `DeniedByPolicy`。
181fn denial_to_terminal(reason: DenialReason) -> ActionState {
182    use aios_spec::intent::DenialReason;
183    match reason {
184        DenialReason::RiskExceedsCapability | DenialReason::ActionCapabilityDenied => {
185            ActionState::DeniedByCapability
186        },
187        _ => ActionState::DeniedByPolicy,
188    }
189}