openclaw/extensions/web4-governance/ARCHITECTURE.md

Web4 Governance Plugin — Architecture & Cross-Project Context

What This Is

The web4-governance plugin is a Tier 1 (Observational) implementation of the Web4 R6 framework, running inside the moltbot agent runtime. It creates verifiable audit trails for every tool call an agent makes, without blocking or requiring approval.

This is the first live integration of Web4 governance into an agent runtime that actually executes tools — not a simulation or demo.

Where It Sits in the Web4 Stack

┌─────────────────────────────────────────────────────────────┐
│                   Hardbound (Tier 2)                        │
│   Full Policy │ Trust Tensors │ ATP │ Hardware Binding       │
│   hardbound-core/src/policy.rs                              │
│   hardbound/src/policy.ts                                   │
└───────────────────────────┬─────────────────────────────────┘
                            │ upgrade path
┌───────────────────────────┴─────────────────────────────────┐
│          web4-governance (Tier 1 + 1.5) ← YOU ARE HERE      │
│   R6 Audit │ Soft LCT │ Hash Chain │ Policy Engine │ CLI    │
│   moltbot/extensions/web4-governance/                       │
└───────────────────────────┬─────────────────────────────────┘
                            │ hooks into
┌───────────────────────────┴─────────────────────────────────┐
│                  Moltbot Agent Runtime                       │
│   pi-tools.hooks.ts (before_tool_call / after_tool_call)    │
│   moltbot/src/agents/pi-tools.ts                            │
└─────────────────────────────────────────────────────────────┘

R6 Implementation Tiers (from web4-standard/core-spec/r6-implementation-guide.md)

Tier	Project	R6 Scope	Trust Model	Enforcement
1 — Observational	web4-governance (this plugin)	Lite: audit_level, session token, tool/category/target/hash, chain position	None (relying party decides)	Record-only
1.5 — Policy	web4-governance (this plugin)	Lite + configurable policy rules, allow/deny/warn, glob/regex matching	Rule-based (first-match-wins)	Block or warn (with dry-run mode)
2 — Authorization	hardbound-core (Rust)	Full: policy rules, actor LCT, team context, ATP, trust delta	T3 tensor (competence, reliability, integrity)	Approve/Reject/Escalate
3 — Training	HRM/SAGE	Training: exercise type, mode detection, meta-cognitive	T3 with developmental trajectory	Include/Exclude/Review

What Was Built (PRs #1 and #2)

PR #1: Tool Call Hooks (src/agents/pi-tools.hooks.ts)

• Wired before_tool_call / after_tool_call typed plugin hooks into moltbot's tool execution pipeline
• before_tool_call can modify params or block execution (returns { block: true, blockReason })
• after_tool_call fires post-execution with result, error, and duration (fire-and-forget)
• This is the hook surface that enables both observation (Tier 1) and enforcement (Tier 2)

PR #2: Web4 Governance Plugin (extensions/web4-governance/)

• R6 framework (src/r6.ts): Creates structured R6 requests from tool calls. Classifies tools into categories (file_read, file_write, command, network, delegation, state). Hashes inputs and extracts targets.
• Audit chain (src/audit.ts): Hash-linked JSONL append log. Each record's prevRecordHash is the SHA-256 prefix of the previous line. Verifiable integrity.
• Session state (src/session-state.ts): Tracks action index, tool/category counts, last R6 ID per session.
• Soft LCT (src/soft-lct.ts): Software-bound identity token from hostname:username hash. Not hardware-bound — that's the Hardbound upgrade path.

Relationship to Hardbound

What's shared (protocol-compatible)

• R6 request structure (Tier 1 is a subset of Tier 2)
• Audit record format (Tier 1 records can be imported into Tier 2)
• Tool categories map to Hardbound ActionType enum
• Hash-linked provenance chain
• Session identity concept (Soft LCT → Hardware LCT upgrade path)

What Hardbound adds (Tier 2, proprietary)

• PolicyEngine (policy.rs): Evaluates R6 requests against rules, roles, trust thresholds, ATP balance. Returns Approve/Reject/Escalate/AutoApprove.
• T3 Trust Tensors: competence, reliability, integrity scoring with context weights
• Coherence Metrics: score + delta tracking with attestation
• ATP Economics: Resource allocation, daily limits, transfer caps
• Hardware Binding: TPM/SE-based LCT (P0 blocker, not yet implemented)
• Governance Rules: Role-based (developer, lead, admin, viewer, guest), action-type scoped, with prohibited requirements and auto-approve thresholds

The upgrade path

The R6 implementation guide documents a progressive adoption model:

1. Start: Install web4-governance plugin (observational audit trail)
2. Grow: Add policy evaluation in before_tool_call (this is the next step)
3. Extend: Connect to Hardbound for full T3/ATP/hardware-bound governance

Tier 1.5: Policy Engine (Implemented)

The policy engine uses the before_tool_call hook to evaluate configurable rules before each tool call. Rules match by tool name, category, and target pattern (glob or regex). Decisions are allow, deny, or warn. Deny decisions block tool execution when enforce: true; in dry-run mode (enforce: false), denials are logged but not enforced.

What was built

• Policy types (src/policy-types.ts): PolicyRule, PolicyMatch, PolicyConfig, PolicyEvaluation, PolicyDecision
• Matchers (src/matchers.ts): Glob-to-regex conversion, list matching, target pattern matching, composite AND-logic rule matching
• PolicyEngine (src/policy.ts): Loads rules, sorts by priority (ascending), first-match-wins evaluation, shouldBlock() for enforcement
• Integration (index.ts): before_tool_call hook evaluates policy and blocks if deny + enforce; after_tool_call picks up stashed evaluation and writes constraints to R6 rules.constraints
• CLI (index.ts): moltbot policy status, moltbot policy rules, moltbot policy test <tool> [target]

Deferred to Phase 2

• Rate limiting (needs windowed counters in session state)
• Config hot-reload
• T3/ATP integration (that's Tier 2 / Hardbound)

What this enables for Hardbound

The upgrade to Tier 2 is:

• Replace rule evaluation with PolicyEngine from hardbound-core
• Add T3 tensor snapshots to audit records
• Add coherence metrics
• Replace Soft LCT with hardware-bound LCT
• Add ATP tracking

The plugin interface stays the same — just the policy evaluation gets richer.

Storage Layout

~/.web4/
├── audit/
│   └── <sessionId>.jsonl     # Hash-linked audit records (append-only)
└── sessions/
    └── <sessionId>.json      # Session metadata (overwritten on each action)

Cross-Project References

File	Project	Relevance
web4-standard/core-spec/r6-implementation-guide.md	web4	Tier definitions, ID formats, upgrade path
web4-standard/core-spec/r6-security-analysis.md	web4	Attack vectors and mitigations
hardbound-core/src/policy.rs	hardbound	Full policy engine (Rust)
hardbound/src/policy.ts	hardbound	TypeScript policy with rule builder
hardbound/tests/policy.test.ts	hardbound	Policy test patterns
hardbound-core/src/r6.rs	hardbound	Full R6 request (Rust)
hardbound/MVP_IMPLEMENTATION.md	hardbound	MVP status, bundle schema, lessons
src/agents/pi-tools.hooks.ts	moltbot	Hook wrapper (our PR #1)
src/plugins/hooks.ts	moltbot	Hook runner (runBeforeToolCall/runAfterToolCall)