flowchart TD
SEAM["Runtime seam · _execute_tool_action (runtime.py)<br/>runs before ANY tool · governance_wiring.py"]
SEAM --> EVAL["evaluate_tool_governance<br/>compute + shadow-log"]
EVAL --> CAPREQ
subgraph GOVF["govern() · authz/govern.py — pure · fail-closed · server-built capability"]
direction TB
CAPREQ["required_capability_for(tool, action)<br/>server-built · never from the LLM"]
CAPS["capabilities_for(owner) · capabilities.py"]
subgraph RISK["Risk classify · authz/risk.py"]
direction TB
RSEC["secret-pattern scan · 15 patterns"]
RPII["PII scan · 6 · heavy tier at high/critical"]
RSIDE["side_effect_level · read / write / irreversible"]
REG["egress_required?"]
RBAND["overall_risk · low / med / high / critical"]
RSEC --> RPII --> RSIDE --> REG --> RBAND
end
POL["decide_policy · authz/policy.py (PDP)<br/>fail-closed precedence → outcome + reason codes"]
DLP["scan_dlp · authz/dlp.py<br/>outbound secrets/PII · fail-safe tighten allow→escalate"]
EGR["check_egress · authz/egress.py · SSRF · host/IP allowlist"]
CHN["check_chain · authz/chain.py · calls/bytes/cross-owner"]
SIGN["sign_event_hash · authz/signing.py · RS256"]
AUD["append_record · authz/audit.py · hash-chained · verify_chain"]
OUTC["GovernanceOutcome<br/>decision · risk · dlp · record · reasons"]
CAPREQ --> CAPS --> RSEC
RBAND --> POL --> DLP --> EGR --> CHN --> SIGN --> AUD --> OUTC
end
OUTC --> GLOG["record_governance_decision<br/>governance_log.py → governance_decisions · RLS"]
OUTC --> ENF["enforce_tool_governance · WIRE-E"]
ENF --> GMODE{"resolve_gate_mode · governance_settings.py<br/>shadow ·or· enforce · read-gate"}
GMODE -->|shadow · default| OBS["observe + log only · never blocks → tool runs"]
GMODE -->|enforce| DECN{"effective decision"}
DECN -->|ALLOW| RUN["tool runs"]
DECN -->|DENY| BLK["block message"]
DECN -->|ESCALATE| ESC["needs approval"]
DECN -->|compute_failed · command| FAIL["fail-closed · GOVERNANCE_UNAVAILABLE"]
subgraph APPR["Operator approval channels"]
direction TB
WTOK["write-action chip / token · LIVE<br/>approval.py · PRD0037 / RFC0072 · gates Gmail/Drive/Calendar writes"]
TG["Telegram approval · telegram_approval.py"]
QUEUE["govern escalate → queue · RFC0090 P4 · planned"]
end
ESC --> WTOK
ESC --> TG
ESC --> QUEUE
WTOK -->|approved| RUN
TG -->|approved| RUN
WTOK -->|denied| BLK
GLOG --> GDB[("DB · writes → steelmoth.governance_decisions · governance_settings_audit · write_action_audit · write_approval_tokens · runtime_context_audit<br/>NOTE: capabilities are CODE, not a table — authz/capabilities.py")]
style GDB fill:#ffffff,stroke:#7c5cff,stroke-width:1px,color:#27272a
style GOVF fill:#fff7ed,stroke:#c2570c,stroke-width:2px,color:#c2570c
style RISK fill:#fff7ed,stroke:#c2570c,stroke-width:1px,color:#c2570c
style APPR fill:#fff7ed,stroke:#c2570c,stroke-width:1px,color:#c2570c
classDef gN fill:#ffffff,stroke:#c2570c,color:#27272a,stroke-width:1px
classDef rN fill:#fdecec,stroke:#e5484d,color:#27272a,stroke-width:1px
classDef aN fill:#ffffff,stroke:#1f9d63,color:#27272a,stroke-width:1px
classDef sN fill:#ffffff,stroke:#475569,color:#27272a,stroke-width:1px
class SEAM,EVAL,CAPREQ,CAPS,RSEC,RPII,RSIDE,REG,RBAND,POL,DLP,EGR,CHN,SIGN,AUD,OUTC,ENF,GMODE,DECN,ESC,WTOK,TG,QUEUE gN
class BLK,FAIL rN
class RUN,OBS aN
class GLOG sN
