建立宿主事件检查档位的 Rust 路由契约

Author: loong10k

crates/codeguard-core/src/hook_event.rs

@@ -0,0 +1,23 @@
+use serde::Serialize;
+
+/// 宿主报告的触发阶段；它本身不是可信代码或 Git 快照。
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HookEvent {
+    /// 会话启动或恢复。
+    SessionStart,
+    /// 用户提交提示；仅供非阻断性意图提示。
+    PromptSubmitted,
+    /// 文件编辑工具完成后。
+    FileChanged,
+    /// 智能体完成一次修复尝试后。
+    RepairReady,
+    /// 提交前。
+    PreCommit,
+    /// 推送前。
+    PrePush,
+    /// 持续集成或正式交付检查。
+    Ci,
+    /// 会话结束。
+    Stop,
+}

crates/codeguard-core/src/hook_trigger_action.rs

@@ -0,0 +1,27 @@
+use serde::Serialize;
+
+/// 一次事件应请求的检查阶段；具体检查器由正式 CheckPlan 决定。
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HookTriggerAction {
+    /// 已确认写入失败，无须启动源码检查。
+    NoCheck,
+    /// 只读观察项目语言与配置。
+    DiscoverProject,
+    /// 根据用户意图展示非阻断性检查建议，不运行 Git 门禁。
+    ShowIntentGuidance,
+    /// 对明确编辑且确认写入的文件提供快速反馈。
+    FastFileCheck,
+    /// 无可靠编辑目标时重新确定范围，不能称为已检查。
+    ResolveChangedScope,
+    /// 按任务身份运行原检查器复检。
+    VerifyTask,
+    /// 对本轮 Git index 内容面运行严格提交门禁。
+    CommitGate,
+    /// 对本轮实际推送 ref 内容面运行严格推送门禁。
+    PushGate,
+    /// 执行完整项目义务。
+    FullProjectCheck,
+    /// 仅汇总本次会话状态。
+    ShowSummary,
+}

crates/codeguard-core/src/hook_trigger_input.rs

@@ -0,0 +1,16 @@
+use crate::{HookEvent, HookWriteOutcome};
+
+/// 宿主事件的未核验输入；规划器不能把它当成代码或 Git 事实。
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct HookTriggerInput {
+    /// 事件阶段。
+    pub event: HookEvent,
+    /// 编辑事件携带的工作区相对路径；交付事件必须重新获取 Git 范围。
+    pub changed_paths: Vec<String>,
+    /// 修复复检事件的稳定任务 ID。
+    pub task_id: Option<String>,
+    /// 宿主对编辑工具写入结果的观察；不证明实际字节身份。
+    pub write_outcome: HookWriteOutcome,
+    /// 宿主声明是否支持可靠阻断；此输入尚未经真实宿主协议验收。
+    pub host_claims_blocking: bool,
+}

crates/codeguard-core/src/hook_trigger_plan.rs

@@ -0,0 +1,22 @@
+use serde::Serialize;
+
+use crate::HookTriggerAction;
+
+/// 事件路由的只读候选计划；没有执行证据，不可签发交付通过。
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+pub struct HookTriggerPlan {
+    /// 本事件请求的检查阶段。
+    pub action: HookTriggerAction,
+    /// 编辑快检的目标路径；交付阶段必须忽略宿主猜测的路径集合。
+    pub target_paths: Vec<String>,
+    /// 原检查器复检目标。
+    pub task_id: Option<String>,
+    /// 是否须从本轮 Git 获取真实提交或推送快照。
+    pub requires_git_snapshot: bool,
+    /// 局部完整结果是否可作为软反馈复用候选；复用仍需核验全部身份。
+    pub soft_result_reuse_candidate: bool,
+    /// 宿主对阻断能力的声明，仅供后续真实宿主核验。
+    pub host_blocking_claimed: bool,
+    /// 规划从不证明检查已完成或允许交付。
+    pub may_claim_delivery: bool,
+}

crates/codeguard-core/src/hook_trigger_planner.rs

@@ -0,0 +1,86 @@
+use std::collections::BTreeSet;
+
+use crate::{HookEvent, HookTriggerAction, HookTriggerInput, HookTriggerPlan, HookWriteOutcome};
+
+/// 把宿主事件映射为检查阶段，交付事件始终要求重新取得真实范围。
+/// 返回候选计划或损坏事件输入；不执行检查、复用缓存或签发门禁结论。
+pub fn plan_hook_trigger(input: &HookTriggerInput) -> Result<HookTriggerPlan, &'static str> {
+    let mut plan = HookTriggerPlan {
+        action: HookTriggerAction::DiscoverProject,
+        target_paths: Vec::new(),
+        task_id: None,
+        requires_git_snapshot: false,
+        soft_result_reuse_candidate: false,
+        host_blocking_claimed: false,
+        may_claim_delivery: false,
+    };
+    match input.event {
+        HookEvent::SessionStart => {}
+        HookEvent::PromptSubmitted => plan.action = HookTriggerAction::ShowIntentGuidance,
+        HookEvent::FileChanged => {
+            let mut seen = BTreeSet::new();
+            for path in &input.changed_paths {
+                if !valid_relative_path(path) {
+                    return Err("hook_changed_path_invalid");
+                }
+                if seen.insert(path.as_str()) {
+                    plan.target_paths.push(path.clone());
+                }
+            }
+            plan.action = match input.write_outcome {
+                HookWriteOutcome::Failed => HookTriggerAction::NoCheck,
+                HookWriteOutcome::Confirmed if !plan.target_paths.is_empty() => {
+                    plan.soft_result_reuse_candidate = true;
+                    HookTriggerAction::FastFileCheck
+                }
+                HookWriteOutcome::Confirmed | HookWriteOutcome::Unknown => {
+                    HookTriggerAction::ResolveChangedScope
+                }
+            };
+        }
+        HookEvent::RepairReady => {
+            let id = input
+                .task_id
+                .as_deref()
+                .filter(|id| valid_task_id(id))
+                .ok_or("hook_task_id_invalid")?;
+            plan.action = HookTriggerAction::VerifyTask;
+            plan.task_id = Some(id.into());
+        }
+        HookEvent::PreCommit => {
+            plan.action = HookTriggerAction::CommitGate;
+            plan.requires_git_snapshot = true;
+            plan.host_blocking_claimed = input.host_claims_blocking;
+        }
+        HookEvent::PrePush => {
+            plan.action = HookTriggerAction::PushGate;
+            plan.requires_git_snapshot = true;
+            plan.host_blocking_claimed = input.host_claims_blocking;
+        }
+        HookEvent::Ci => {
+            plan.action = HookTriggerAction::FullProjectCheck;
+            plan.host_blocking_claimed = input.host_claims_blocking;
+        }
+        HookEvent::Stop => plan.action = HookTriggerAction::ShowSummary,
+    }
+    Ok(plan)
+}
+
+fn valid_relative_path(path: &str) -> bool {
+    !path.is_empty()
+        && !path.starts_with('/')
+        && !path.contains('\\')
+        && !path.chars().any(char::is_control)
+        && path
+            .split('/')
+            .all(|part| !part.is_empty() && part != "." && part != "..")
+}
+
+fn valid_task_id(id: &str) -> bool {
+    id.len() > 3
+        && id.len() <= 64
+        && id.starts_with("CG-")
+        && id[3..]
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
+}

crates/codeguard-core/src/hook_write_outcome.rs

@@ -0,0 +1,13 @@
+use serde::Serialize;
+
+/// 编辑工具的写入结果；失败不触发源码检查，未知结果需重新确定范围。
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HookWriteOutcome {
+    /// 宿主确认写入成功；仍须核对真实源码身份。
+    Confirmed,
+    /// 宿主确认未写入。
+    Failed,
+    /// 宿主无法确认是否写入。
+    Unknown,
+}

crates/codeguard-core/src/lib.rs

@@ -10,6 +10,12 @@ mod delivery_gate;
 mod evaluation;
 mod false_positive_allowlist;
 mod finding;
+mod hook_event;
+mod hook_trigger_action;
+mod hook_trigger_input;
+mod hook_trigger_plan;
+mod hook_trigger_planner;
+mod hook_write_outcome;
 mod native_checker_binding;
 mod obligation_result;
 mod observation_port;
@@ -45,6 +51,12 @@ pub use false_positive_allowlist::{
     valid_false_positive_identity,
 };
 pub use finding::{Finding, FindingLocation, GateImpact};
+pub use hook_event::HookEvent;
+pub use hook_trigger_action::HookTriggerAction;
+pub use hook_trigger_input::HookTriggerInput;
+pub use hook_trigger_plan::HookTriggerPlan;
+pub use hook_trigger_planner::plan_hook_trigger;
+pub use hook_write_outcome::HookWriteOutcome;
 pub use native_checker_binding::NativeCheckerBinding;
 pub use obligation_result::ObligationResult;
 pub use observation_port::{ObservationPort, ObservedPathKind};

crates/codeguard-core/tests/hook_trigger_plan.rs

@@ -0,0 +1,113 @@
+use codeguard_core::{
+    HookEvent, HookTriggerAction, HookTriggerInput, HookWriteOutcome, plan_hook_trigger,
+};
+
+fn request(event: HookEvent) -> HookTriggerInput {
+    HookTriggerInput {
+        event,
+        changed_paths: Vec::new(),
+        task_id: None,
+        write_outcome: HookWriteOutcome::Unknown,
+        host_claims_blocking: true,
+    }
+}
+
+#[test]
+fn startup_and_stop_do_not_execute_quality_checks() {
+    let startup = plan_hook_trigger(&request(HookEvent::SessionStart)).unwrap();
+    assert_eq!(startup.action, HookTriggerAction::DiscoverProject);
+    assert!(!startup.requires_git_snapshot);
+    let stop = plan_hook_trigger(&request(HookEvent::Stop)).unwrap();
+    assert_eq!(stop.action, HookTriggerAction::ShowSummary);
+    assert!(!stop.may_claim_delivery);
+    let prompt = plan_hook_trigger(&request(HookEvent::PromptSubmitted)).unwrap();
+    assert_eq!(prompt.action, HookTriggerAction::ShowIntentGuidance);
+    assert!(!prompt.requires_git_snapshot);
+    assert!(!prompt.may_claim_delivery);
+}
+
+#[test]
+fn successful_edit_requests_only_file_feedback() {
+    let mut input = request(HookEvent::FileChanged);
+    input.write_outcome = HookWriteOutcome::Confirmed;
+    input.changed_paths = vec!["src/A.java".into(), "src/B.java".into()];
+    let plan = plan_hook_trigger(&input).unwrap();
+    assert_eq!(plan.action, HookTriggerAction::FastFileCheck);
+    assert_eq!(plan.target_paths, input.changed_paths);
+    assert!(plan.soft_result_reuse_candidate);
+    assert!(!plan.may_claim_delivery);
+    assert!(!plan.requires_git_snapshot);
+}
+
+#[test]
+fn uncertain_edit_or_missing_target_cannot_be_silently_skipped() {
+    let mut input = request(HookEvent::FileChanged);
+    input.write_outcome = HookWriteOutcome::Confirmed;
+    assert_eq!(
+        plan_hook_trigger(&input).unwrap().action,
+        HookTriggerAction::ResolveChangedScope
+    );
+    input.changed_paths = vec!["src/A.java".into()];
+    input.write_outcome = HookWriteOutcome::Unknown;
+    assert_eq!(
+        plan_hook_trigger(&input).unwrap().action,
+        HookTriggerAction::ResolveChangedScope
+    );
+    input.changed_paths = vec!["../outside.java".into()];
+    assert!(plan_hook_trigger(&input).is_err());
+}
+
+#[test]
+fn failed_write_does_not_start_a_source_check() {
+    let mut input = request(HookEvent::FileChanged);
+    input.write_outcome = HookWriteOutcome::Failed;
+    input.changed_paths = vec!["src/A.java".into()];
+    let plan = plan_hook_trigger(&input).unwrap();
+    assert_eq!(plan.action, HookTriggerAction::NoCheck);
+    assert!(!plan.soft_result_reuse_candidate);
+}
+
+#[test]
+fn repair_requests_original_task_verification() {
+    let mut input = request(HookEvent::RepairReady);
+    input.task_id = Some("CG-abc123".into());
+    let plan = plan_hook_trigger(&input).unwrap();
+    assert_eq!(plan.action, HookTriggerAction::VerifyTask);
+    assert_eq!(plan.task_id.as_deref(), Some("CG-abc123"));
+    assert!(!plan.soft_result_reuse_candidate);
+    assert!(plan_hook_trigger(&request(HookEvent::RepairReady)).is_err());
+}
+
+#[test]
+fn delivery_events_always_request_current_git_or_project_scope() {
+    for (event, action) in [
+        (HookEvent::PreCommit, HookTriggerAction::CommitGate),
+        (HookEvent::PrePush, HookTriggerAction::PushGate),
+        (HookEvent::Ci, HookTriggerAction::FullProjectCheck),
+    ] {
+        let mut input = request(event);
+        input.changed_paths = vec!["src/A.java".into()];
+        let plan = plan_hook_trigger(&input).unwrap();
+        assert_eq!(plan.action, action);
+        assert!(
+            plan.target_paths.is_empty(),
+            "caller paths cannot define delivery scope"
+        );
+        assert!(!plan.soft_result_reuse_candidate);
+        assert_eq!(plan.requires_git_snapshot, event != HookEvent::Ci);
+        assert!(
+            !plan.may_claim_delivery,
+            "planning is never proof of a gate"
+        );
+    }
+}
+
+#[test]
+fn nonblocking_host_cannot_claim_a_strict_gate() {
+    let mut input = request(HookEvent::PreCommit);
+    input.host_claims_blocking = false;
+    let plan = plan_hook_trigger(&input).unwrap();
+    assert_eq!(plan.action, HookTriggerAction::CommitGate);
+    assert!(!plan.host_blocking_claimed);
+    assert!(!plan.may_claim_delivery);
+}

docs/Codeguard-Architecture.md

@@ -309,6 +309,34 @@ For required setup, create one setup/confirmation task per module/checker obliga
 
 Allowlist dispositions bind rule, source target, grammar identity and reason; retain observations and reevaluate after relevant changes. They cannot remove required native checking or fabricate coverage. Repeated runs update stable tasks and attempt history. Emit the initial brief, then meaningful changes; preserve a status view instead of repeating unchanged installation requests. See the technical design's **7.3–7.4** for bilingual report examples and the proposed data contract.
 
+### 8.4 Host events and check tiers — target
+
+Host hooks pass events, workspace identity and known targets. Rust core selects the check tier; the formal CheckPlan then chooses native checkers and resource budgets. An agent cannot change delivery obligations through a prompt, an old soft cache entry or a project-local `skipGate`. This remains a target design: the [pure domain router](../crates/codeguard-core/src/hook_trigger_planner.rs) has unit coverage, but no plugin, CLI or real Git/CI wiring and no verified automatic host trigger yet.
+
+```mermaid
+flowchart LR
+    H[Host event] --> R[Pure Rust event routing]
+    R -->|Session start| D[Read-only discovery]
+    R -->|Confirmed edit| F[Changed-file feedback]
+    R -->|Repair ready| V[Original task and checker recheck]
+    R -->|Commit / push| G[Acquire current Git content scope]
+    R -->|CI| A[Full project obligations]
+    F --> P[Unified report / task / next action]
+    V --> P
+    G --> P
+    A --> P
+```
+
+| Event | Requested tier | Required boundary |
+| :--- | :--- | :--- |
+| Start/resume, prompt, stop | Read-only discovery, nonblocking intent guidance, session summary | Prompt text cannot replace a real Git gate or claim delivery |
+| Confirmed write | Affected-file fast check | Reuse a complete soft result only when content and all configuration identities match; queue project-wide work |
+| Failed/unknown write | No source check / resolve scope | Unknown cannot mean unchanged or checked |
+| Repair attempt completed | Original `task verify` | Installing a tool, ticking a task or WASM clean alone does not close it |
+| Commit, push, CI | Strict commit scope, actual pushed refs, full project obligations | Ignore host-supplied path guesses and old save feedback; disclose missing enforcement support |
+
+Coalescing applies only to duplicate fast feedback for the same content snapshot; it cannot swallow new input, failed rechecks or delivery events. Cache identity must cover source and dependency closure, tool, rules, configuration, platform and vulnerability database freshness. Strict gates revalidate full obligations and identities, then recompute or report incomplete when proof is missing. Measure latency percentiles, repeat execution, invalidations, missed findings and false positives per tier before fixing budgets.
+
 ## 9. Persistence and ownership
 
 ```text