Struct RuleCache 

pub struct RuleCache { /* private fields */ }

Per-instance cache of Vec<Rule> keyed by AgentAction::kind().

The cache is owned by a Connection-bearing context (HTTP AppState, MCP main loop, or the substrate GOVERNANCE_PRE_WRITE / GOVERNANCE_PRE_ACTION hook installer that captures a long-lived Connection). Pass &RuleCache (or wrap in Arc for shared ownership) to the cached entry points (check_agent_action_cached, etc.). Cache hits return an Arc<Vec<Rule>> clone — no row data is cloned on the fast path.

Implementations

impl RuleCache

pub fn new() -> Self

Construct an empty cache. Cheap; safe to call per-test.

pub fn get_or_load( &self, conn: &Connection, kind: &str, ) -> Result<Arc<Vec<Rule>>, RuleCacheError>

Return the cached rule list for kind, loading via crate::governance::rules_store::list_enabled_by_kind on cache miss. The Ed25519 signature verify side-effect on the loader path runs on miss; cache hits skip it.

v0.7.0 #1020 (Agent-1 #6) — returns the typed RuleCacheError enum at the substrate-public boundary (was bare anyhow::Result pre-#1020). RuleCacheError: Into<anyhow::Error> is implemented so existing anyhow-chained callers can keep their ? operator with no signature changes.

Errors

• RuleCacheError::Load wraps any error from list_enabled_by_kind (rusqlite errors, signature-verify panics).
• RuleCacheError::Poisoned indicates the inner RwLock is poisoned by a prior thread panic. The legacy fallback returned a fresh snapshot anyway; callers wanting that posture can branch via RuleCacheError::is_poisoned and re-call list_enabled_by_kind directly.

pub fn invalidate(&self, kind: &str)

Drop the cached entry for kind. Currently no caller takes this path because the rules_store writers don’t know the affected kind without inspecting the row; Self::invalidate_all is simpler.

pub fn invalidate_all(&self)

Drop every cached entry. Used by the rules_store write paths (insert / remove / set_enabled / update_signature) so the next reader rebuilds against the post-write state.

pub fn len(&self) -> usize

Number of currently-cached entries — for test inspection.

#1018 (2026-05-21): poison semantics changed from “lie as empty” to “return None via Self::len_checked”. The legacy len() returns 0 on poison (matches the pre-#1018 contract some tests still depend on); call sites that need to distinguish “empty” from “poisoned” use len_checked.

pub fn len_checked(&self) -> Option<usize>

#1018 (2026-05-21): poison-aware variant of Self::len. Returns Some(len) on a healthy lock, None if the RwLock is poisoned. Pre-#1018 a poisoned cache reported len() == 0 and is_empty() == true — invisible to callers and test assertions. Operator inspection paths + future health-probe surfaces should consume this variant; legacy paths keep len().

pub fn is_empty(&self) -> bool

Whether the cache is empty — for test inspection.

#1018: the legacy contract treats poison as “empty” (returns true). Use Self::is_empty_checked when the distinction matters.

pub fn is_empty_checked(&self) -> Option<bool>

#1018 (2026-05-21): poison-aware variant of Self::is_empty. Returns Some(true) when the cache is healthy AND empty, Some(false) when healthy AND populated, None when the RwLock is poisoned. Operator inspection paths use this.

Trait Implementations

impl Debug for RuleCache

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RuleCache

fn default() -> RuleCache

Returns the “default value” for a type.