agentstategraph_policy/lib.rs
1//! Policy primitive for AgentStateGraph.
2//!
3//! Fourth-primitive sibling crate, parallel to `agentstategraph-tasks`.
4//! Implements the authorization + change-cost primitive of the Policy v1
5//! design (§§2-7 and §22; user guide: `docs/POLICY_GUIDE.md`). Ships the engine
6//! surface only — MCP tools, CLI, and Lens UI live in their respective
7//! consumer crates.
8//!
9//! # What this crate is
10//!
11//! - `Policy` schema (situation-matching rules + procedure + change-cost
12//! gating fields)
13//! - `PolicyStore` — a handle bound to a `Repository` + prefix with
14//! `propose` / `ratify` / `supersede` / `evaluate` / `evaluate_change`
15//! - `Selector` — a tagged-enum boolean expression over a `Situation`
16//! - `Decision` — the evaluator's result, including `RequireApproval`
17//! with a `FallbackAction` ("what to do while it waits")
18//!
19//! # What this crate is NOT
20//!
21//! - Not an enforcement layer (soft model — see POLICY_V1.md §11)
22//! - Not a Rego/Cedar clone (the selector is a minimal DSL; external
23//! policy engines are a future escape hatch)
24//! - Not an MCP tool or CLI — those belong to consumers
25//!
26//! # Example
27//!
28//! ```rust,no_run
29//! use agentstategraph::Repository;
30//! use agentstategraph_storage::SqliteStorage;
31//! use agentstategraph_policy::{PolicyStore, Situation, Selector};
32//! use std::sync::Arc;
33//!
34//! let repo = Arc::new(Repository::new(Box::new(SqliteStorage::in_memory().expect("in-memory sqlite"))));
35//! repo.init().unwrap();
36//! let store = PolicyStore::new(repo, "/policies", "claude-code");
37//! // propose, ratify, evaluate ...
38//! let _ = store.evaluate("main", &Situation::new(), "restart_pod", "agent-1");
39//! ```
40
41pub mod error;
42pub mod evaluator;
43pub mod external;
44pub mod paths;
45pub mod selector;
46pub mod store;
47pub mod types;
48pub mod verifier;
49
50pub use error::PolicyError;
51pub use external::{ExternalError, ExternalEvaluator, ExternalEvaluatorRegistry};
52pub use selector::{Selector, Situation};
53pub use store::PolicyStore;
54pub use types::{
55 ApprovalRule, AuthorizedAction, ChangeProposal, Decision, EvaluatorSource,
56 ExternalEvaluatorRef, FallbackAction, Policy, PolicySignature, ProcedureStep, Severity,
57};
58pub use verifier::{SignatureVerificationError, SignatureVerifier};