Governance
Three-branch constitutional governance: rules, EffectVector scoring, how the engine decides, the GateBackend trait, genesis rules, project overlays, workload governance and environment scoping.
WeftOS implements a three-branch constitutional governance model. Actions an agent takes are evaluated against a set of rules anchored to the chain at genesis.
Source: crates/clawft-kernel/src/governance.rs (engine, rules, requests), gate.rs (GateBackend and its implementations), governance_overlay.rs and governance_project.rs (per-project overlay, ADR-103), workload_governance/ (workload actions, ADR-099), environment.rs (environment classes).
Three-branch model
Legislative Executive Judicial
SOPs, manifests, agent execution validation, bias checks,
genesis rules, policies, deployment, audit compliance
data protection lifecycleEach rule carries a GovernanceBranch (Legislative, Executive, Judicial). Rules are written to the chain at boot as genesis events, so a rule's branch and severity are anchored in the audit trail. This page does not claim that branches are separate enforcement processes: the engine evaluates one flat list of active rules.
GovernanceRule
pub struct GovernanceRule {
pub id: String,
pub description: String,
pub branch: GovernanceBranch,
pub severity: RuleSeverity, // Advisory, Warning, Blocking, Critical
pub active: bool, // default true
pub reference_url: Option<String>,
pub sop_category: Option<String>,
pub rule_type: GovernanceRuleType, // General (default), BrowserPolicy, BindingThread
pub action_selector: Option<String>,
pub tool_selector: Option<String>,
pub force_on_match: bool,
}Selectors are an exact action or a prefix ending in one *. A rule with a selector is skipped unless the request matches it. force_on_match makes a rule apply on the selector match alone, regardless of effect magnitude.
Request, decision and effect
pub struct GovernanceRequest {
pub agent_id: String,
pub action: String,
pub effect: EffectVector,
pub context: HashMap<String, String>,
pub node_id: Option<String>,
pub principal: Option<GatePrincipal>,
}
pub enum GovernanceDecision {
Permit,
PermitWithWarning(String),
EscalateToHuman(String),
Deny(String),
}
pub struct EffectVector { pub risk: f64, pub fairness: f64, pub privacy: f64, pub novelty: f64, pub security: f64 }The effect score is the L2 magnitude of the five dimensions, sqrt(risk^2 + fairness^2 + privacy^2 + novelty^2 + security^2). With the ecc feature a trained GovernanceScorerModel can replace it; without a model score returns the magnitude unchanged.
How GovernanceEngine::evaluate decides
Read from governance.rs, GovernanceEngine::evaluate:
- A per-principal evaluation rate limit is checked first. Over quota is an immediate
Deny. threshold_exceededis true when the score is greater than the engine'srisk_threshold.- Each active rule whose selectors match is evaluated:
BrowserPolicyrules fire on platform and context match, independent of magnitude. A blocking match sets the block flags; a non-blocking match only records a warning.BindingThreadrules (soul.binding_thread_intact) fire when the request signals a binding-thread mismatch, independent of magnitude. Their reason text outranks any other rule's.Generalrules apply when the threshold is exceeded orforce_on_matchis set.BlockingandCriticalset the block flags;Warningsets the warning flag;Advisoryhas no effect on the decision.
- The decision:
- any blocking rule applied:
EscalateToHumanwhen the engine requires human approval (or an overlay approval rule applied and no other blocking rule did), unless an overlay deny rule applied; otherwiseDeny; - else, threshold exceeded and a warning set:
PermitWithWarning; - else
Permit.
- any blocking rule applied:
The first blocking rule in evaluation order supplies the decision text. Since 0.8.4-rc.15 a non-blocking browser-policy match no longer clears a block set by an earlier rule, so the decision does not depend on rule order (CHANGELOG 0.8.4-rc.15, "Governance").
Dual-layer enforcement (Symposium D7)
At boot the governance gate is wired into the A2A router (boot.rs, "Wire governance gate into A2A router for dual-layer enforcement"), so a message is checked at routing and again at the receiving handler.
GateBackend
pub trait GateBackend: Send + Sync {
fn check(&self, agent_id: &str, action: &str, context: &Value) -> GateDecision;
}
pub enum GateDecision {
Permit { token: Option<Vec<u8>> },
Defer { reason: String },
Deny { reason: String, receipt: Option<String> },
}Implementations in gate.rs: CapabilityGate, GovernanceGate and, with the tilezero feature, TileZeroGate.
Environment scoping
pub enum EnvironmentClass { Development, Staging, Production, Custom { name: String, risk_threshold: f64 } }Risk thresholds: Development 0.9, Staging 0.6, Production 0.3, Custom as given (environment.rs, EnvironmentClass::risk_threshold). A GovernanceScope also sets the audit level (SessionSummary by default, PerAction, PerActionWithEffects) and a learning mode (Explore by default, Validate, Exploit).
Default genesis rules
boot.rs anchors 22 SOP and constitutional rules (GOV-001 to GOV-007, SOP-L001 to SOP-L006, SOP-E001 to SOP-E005, SOP-J001 to SOP-J004), counted by branch and severity from the rule literals:
| Branch | Count | Blocking | Warning | Advisory |
|---|---|---|---|---|
| Legislative | 8 | 2 | 5 | 1 |
| Executive | 7 | 2 | 2 | 3 |
| Judicial | 7 | 3 | 2 | 2 |
Boot adds more rules to that set: three browser-policy rules (BP-001 to BP-003: public topics only, no spawn and no network without elevation), the binding-thread rule, and the two workload rules (below). A project kernel replaces the set with the effective rules from its signed parent policy plus overlay (ADR-103 D8).
Project overlay
A project can tighten, but never relax, its parent's rules with <root>/.weftos/overlay.toml (governance_overlay.rs). Each deny glob becomes a blocking rule tagged project-overlay:deny that answers Deny even when engine-wide human approval is on. Each require_approval glob becomes a rule tagged project-overlay:approval that answers EscalateToHuman. A missing file is the empty overlay; an unreadable or unparseable file is an error, never silently fewer rules.
Workload governance
workload.* actions are default-deny (ADR-099 section 4). workload_governance::default_rules adds a force-match blocking rule that denies every workload.* action unless an explicit permit rule matches, and an effect-ceiling rule that denies workload actions above the effect threshold even when permitted. WorkloadGate enforces the policy, checks subject revocations and chains each decision. See Placement.
Chain events
| Event kind | Trigger |
|---|---|
governance.genesis | Boot (constitution) |
governance.rule | Boot (per-rule anchor) |
governance.permit | Permit |
governance.warn | PermitWithWarning |
governance.defer | EscalateToHuman |
governance.deny | Deny |
The four decision kinds are mapped in crates/clawft-kernel/src/chain.rs; governance.genesis and governance.rule are written in boot.rs.
ExoChain Subsystem
Append-only hash chain with SHAKE-256, Ed25519 and ML-DSA-65 dual signing, RVF persistence, witness chains, and integrity verification.
ECC Cognitive Substrate
Ephemeral Causal Cognition: causal DAG, cognitive tick, cross-references, HNSW vector search, impulse queue, calibration, and the three operating modes.