incident_correlation/lib.rs
1//! # incident-correlation
2//!
3//! Walks the Kinetic Gain Protocol Suite document graph starting from an
4//! AI Incident Card and emits a structured remediation plan.
5//!
6//! ## What it answers
7//!
8//! When something goes wrong with a deployed AI system, the operator writes
9//! an **AI Incident Card** that references the affected pieces — usually a
10//! tool, an agent, or a specific vendor's AEO entity. The honest question
11//! after that is: *what else does this incident touch?*
12//!
13//! - Which **agent-cards** depend on the affected tool?
14//! - Which **decision-cards** approved the affected vendor?
15//! - Which **AEO entities** declare the affected entity in their authority chain?
16//! - Which **active conditions** on those decisions might now be in breach?
17//!
18//! `IncidentCorrelator::correlate` walks the graph and returns a
19//! [`RemediationPlan`] with each affected node + a suggested action.
20//!
21//! ## Design
22//!
23//! - The graph is a `petgraph::Graph` of [`SuiteNode`]s.
24//! - Edges are typed ([`SuiteEdge::DependsOn`], [`SuiteEdge::ApprovedBy`],
25//! [`SuiteEdge::Mentions`]), so the correlator can answer "what depends on
26//! X" with one BFS over a typed edge filter.
27//! - The whole pipeline is synchronous because graph work doesn't need an
28//! executor. `tokio` only shows up in dev-deps for the test harness.
29//!
30//! ## Composes with
31//!
32//! - **[procurement-decision-api](https://github.com/mizcausevic-dev/procurement-decision-api)** —
33//! the Decision Cards this crate walks across.
34//! - **[policy-as-code-engine](https://github.com/mizcausevic-dev/policy-as-code-engine)** —
35//! the remediation plan can drive `force_recheck` calls against the
36//! PolicyBundles those cards produce.
37//! - **[aeo-validator-service](https://github.com/mizcausevic-dev/aeo-validator-service)** —
38//! re-validate the affected AEO docs with one call each.
39
40#![warn(missing_docs)]
41#![warn(rust_2018_idioms)]
42#![warn(clippy::pedantic)]
43#![allow(clippy::module_name_repetitions)]
44#![allow(clippy::missing_errors_doc)]
45#![allow(clippy::missing_panics_doc)]
46#![allow(clippy::must_use_candidate)]
47#![allow(clippy::doc_markdown)]
48#![allow(clippy::match_same_arms)]
49
50pub mod correlator;
51pub mod error;
52pub mod graph;
53pub mod model;
54pub mod plan;
55
56/// Optional audit-stream-py producer. Gated behind the `audit-stream`
57/// Cargo feature so the core graph crate stays sync and HTTP-free.
58#[cfg(feature = "audit-stream")]
59pub mod audit_stream;
60
61pub use correlator::IncidentCorrelator;
62pub use error::CorrelationError;
63pub use graph::{SuiteEdge, SuiteGraph, SuiteNode};
64pub use model::{IncidentCard, NodeKind};
65pub use plan::{Action, AffectedNode, RemediationPlan};