# VAULTMESH-CONSTITUTIONAL-GOVERNANCE.md
**The Laws That Govern the Ledger**

> *A civilization without laws is just a database.*

Constitutional Governance defines the rules, amendments, and enforcement mechanisms that govern VaultMesh itself. This is the meta-layer — the constitution that the engines must obey.

---

## 1. Governance Philosophy

### 1.1 Why a Constitution?

VaultMesh isn't just infrastructure — it's a **trust machine**. Trust requires:
- **Predictability**: Rules don't change arbitrarily
- **Transparency**: Changes are visible and receipted
- **Legitimacy**: Changes follow defined procedures
- **Accountability**: Violations have consequences

The Constitution provides these guarantees.

### 1.2 Constitutional Hierarchy

```
┌─────────────────────────────────────────────────────┐
│  IMMUTABLE AXIOMS                                   │
│  (Cannot be changed, ever)                          │
│  • Receipts are append-only                         │
│  • Hashes are cryptographically verified            │
│  • All changes are receipted                        │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│  CONSTITUTIONAL ARTICLES                            │
│  (Can be amended with supermajority + ratification) │
│  • Governance procedures                            │
│  • Engine authorities                               │
│  • Federation rules                                 │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│  STATUTORY RULES                                    │
│  (Can be changed with standard procedures)          │
│  • Operational parameters                           │
│  • Default configurations                           │
│  • Policy settings                                  │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│  EXECUTIVE ORDERS                                   │
│  (Can be issued by authorized actors)               │
│  • Emergency responses                              │
│  • Temporary measures                               │
│  • Operational decisions                            │
└─────────────────────────────────────────────────────┘
```

---

## 2. Governance Scroll

| Property | Value |
|----------|-------|
| **Scroll Name** | `Governance` |
| **JSONL Path** | `receipts/governance/governance_events.jsonl` |
| **Root File** | `ROOT.governance.txt` |
| **Receipt Types** | `gov_proposal`, `gov_vote`, `gov_ratification`, `gov_amendment`, `gov_executive_order`, `gov_violation`, `gov_enforcement` |

---

## 3. The Constitution

### 3.1 Preamble

```markdown
# VAULTMESH CONSTITUTION v1.0

We, the architects and stewards of VaultMesh, establish this Constitution to:

1. Preserve the integrity of the Civilization Ledger
2. Ensure transparent and accountable governance
3. Protect the sovereignty of all participants
4. Enable durable, cross-generational trust

This Constitution is the supreme law of this VaultMesh instance.
All engines, agents, and actors are bound by its provisions.
```

### 3.2 Immutable Axioms

```json
{
  "axioms": [
    {
      "id": "AXIOM-001",
      "name": "Append-Only Receipts",
      "statement": "Receipts, once written, shall never be modified or deleted. The ledger is append-only.",
      "rationale": "Immutability is the foundation of trust.",
      "immutable": true
    },
    {
      "id": "AXIOM-002",
      "name": "Cryptographic Integrity",
      "statement": "All receipts shall include cryptographic hashes computed from their content. Hash algorithms may be upgraded but never weakened.",
      "rationale": "Verification requires mathematical certainty.",
      "immutable": true
    },
    {
      "id": "AXIOM-003",
      "name": "Universal Receipting",
      "statement": "All significant state changes shall produce receipts. No governance action is valid without a receipt.",
      "rationale": "What is not receipted did not happen.",
      "immutable": true
    },
    {
      "id": "AXIOM-004",
      "name": "Constitutional Supremacy",
      "statement": "No engine, agent, or actor may take action that violates this Constitution. Violations are void ab initio.",
      "rationale": "The Constitution is the root of legitimacy.",
      "immutable": true
    },
    {
      "id": "AXIOM-005",
      "name": "Axiom Immutability",
      "statement": "These axioms cannot be amended, suspended, or circumvented by any procedure.",
      "rationale": "Some truths must be eternal.",
      "immutable": true
    }
  ]
}
```

### 3.3 Constitutional Articles

```json
{
  "articles": [
    {
      "id": "ARTICLE-I",
      "name": "Governance Structure",
      "sections": [
        {
          "id": "I.1",
          "title": "Sovereign Authority",
          "text": "The Sovereign (designated human administrator) holds ultimate authority over this VaultMesh instance, subject to the Axioms."
        },
        {
          "id": "I.2",
          "title": "Engine Authorities",
          "text": "Each Engine operates within its defined domain. No Engine may exceed its constitutional authority."
        },
        {
          "id": "I.3",
          "title": "Agent Delegation",
          "text": "Agents may exercise delegated authority within explicit bounds. All agent actions are attributable to their delegator."
        }
      ]
    },
    {
      "id": "ARTICLE-II",
      "name": "Amendment Procedure",
      "sections": [
        {
          "id": "II.1",
          "title": "Proposal",
          "text": "Constitutional amendments may be proposed by the Sovereign or by consensus of admin-capability holders."
        },
        {
          "id": "II.2",
          "title": "Deliberation Period",
          "text": "All amendments require a minimum 7-day deliberation period before voting."
        },
        {
          "id": "II.3",
          "title": "Ratification",
          "text": "Amendments require approval by the Sovereign AND successful execution of the amendment receipt."
        },
        {
          "id": "II.4",
          "title": "Effective Date",
          "text": "Amendments take effect upon anchor confirmation of the ratification receipt."
        }
      ]
    },
    {
      "id": "ARTICLE-III",
      "name": "Engine Governance",
      "sections": [
        {
          "id": "III.1",
          "title": "Engine Registry",
          "text": "Only engines registered in the Constitution may operate. New engines require constitutional amendment."
        },
        {
          "id": "III.2",
          "title": "Engine Boundaries",
          "text": "Each engine's authority is limited to its defined scroll(s). Cross-scroll operations require explicit authorization."
        },
        {
          "id": "III.3",
          "title": "Engine Lifecycle",
          "text": "Engines may be suspended or deprecated by executive order, but removal requires amendment."
        }
      ]
    },
    {
      "id": "ARTICLE-IV",
      "name": "Rights and Protections",
      "sections": [
        {
          "id": "IV.1",
          "title": "Audit Rights",
          "text": "Any authorized party may audit any receipt. Audit requests shall not be unreasonably denied."
        },
        {
          "id": "IV.2",
          "title": "Data Sovereignty",
          "text": "Data subjects retain rights over their personal data as defined by applicable law."
        },
        {
          "id": "IV.3",
          "title": "Due Process",
          "text": "No capability shall be revoked without notice and opportunity to respond, except in emergencies."
        }
      ]
    },
    {
      "id": "ARTICLE-V",
      "name": "Federation",
      "sections": [
        {
          "id": "V.1",
          "title": "Federation Authority",
          "text": "Federation agreements require Sovereign approval."
        },
        {
          "id": "V.2",
          "title": "Federation Limits",
          "text": "No federation agreement may compromise the Axioms or require violation of this Constitution."
        },
        {
          "id": "V.3",
          "title": "Federation Termination",
          "text": "Federation agreements may be terminated with 30 days notice, or immediately upon material breach."
        }
      ]
    },
    {
      "id": "ARTICLE-VI",
      "name": "Emergency Powers",
      "sections": [
        {
          "id": "VI.1",
          "title": "Emergency Declaration",
          "text": "The Sovereign may declare an emergency upon credible threat to system integrity."
        },
        {
          "id": "VI.2",
          "title": "Emergency Powers",
          "text": "During emergencies, the Sovereign may suspend normal procedures except the Axioms."
        },
        {
          "id": "VI.3",
          "title": "Emergency Duration",
          "text": "Emergencies automatically expire after 72 hours unless renewed. All emergency actions must be receipted."
        }
      ]
    }
  ]
}
```

### 3.4 Engine Registry

```json
{
  "registered_engines": [
    {
      "engine_id": "engine:drills",
      "name": "Security Drills",
      "scroll": "Drills",
      "authority": "Security training and exercise management",
      "registered_at": "2025-06-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:oracle",
      "name": "Compliance Oracle",
      "scroll": "Compliance",
      "authority": "Compliance question answering and attestation",
      "registered_at": "2025-06-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:guardian",
      "name": "Guardian",
      "scroll": "Guardian",
      "authority": "Anchoring, monitoring, and security response",
      "registered_at": "2025-06-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:treasury",
      "name": "Treasury",
      "scroll": "Treasury",
      "authority": "Financial tracking and settlement",
      "registered_at": "2025-12-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:mesh",
      "name": "Mesh",
      "scroll": "Mesh",
      "authority": "Topology and federation management",
      "registered_at": "2025-12-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:offsec",
      "name": "OffSec",
      "scroll": "OffSec",
      "authority": "Security operations and incident response",
      "registered_at": "2025-12-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:identity",
      "name": "Identity",
      "scroll": "Identity",
      "authority": "DID, credential, and capability management",
      "registered_at": "2025-12-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:observability",
      "name": "Observability",
      "scroll": "Observability",
      "authority": "Telemetry and health monitoring",
      "registered_at": "2025-12-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:automation",
      "name": "Automation",
      "scroll": "Automation",
      "authority": "Workflow and agent execution",
      "registered_at": "2025-12-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:psi",
      "name": "Psi-Field",
      "scroll": "PsiField",
      "authority": "Consciousness and transmutation tracking",
      "registered_at": "2025-12-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:federation",
      "name": "Federation",
      "scroll": "Federation",
      "authority": "Cross-mesh trust and verification",
      "registered_at": "2025-12-01T00:00:00Z",
      "status": "active"
    },
    {
      "engine_id": "engine:governance",
      "name": "Governance",
      "scroll": "Governance",
      "authority": "Constitutional enforcement and amendment",
      "registered_at": "2025-06-01T00:00:00Z",
      "status": "active"
    }
  ]
}
```

---

## 4. Governance Procedures

### 4.1 Amendment Workflow

```
┌──────────────┐
│   PROPOSAL   │
│              │
│ Author drafts│
│ amendment    │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ SUBMISSION   │
│              │
│ Submit via   │
│ gov_proposal │
│ receipt      │
└──────┬───────┘
       │
       ▼
┌──────────────┐     7+ days
│ DELIBERATION │◄────────────┐
│              │             │
│ Public       │  Comments   │
│ discussion   │─────────────┘
└──────┬───────┘
       │
       ▼
┌──────────────┐
│    VOTING    │
│              │
│ Sovereign +  │
│ Admin quorum │
└──────┬───────┘
       │
       ├─────── REJECTED ──────► Archive
       │
       ▼ APPROVED
┌──────────────┐
│ RATIFICATION │
│              │
│ Sovereign    │
│ signs        │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  ACTIVATION  │
│              │
│ Upon anchor  │
│ confirmation │
└──────────────┘
```

### 4.2 Proposal Receipt

```json
{
  "type": "gov_proposal",
  "proposal_id": "PROP-2025-12-001",
  "proposal_type": "amendment",
  "title": "Add Data Retention Article",
  "author": "did:vm:human:sovereign",
  "submitted_at": "2025-12-06T10:00:00Z",
  "deliberation_ends": "2025-12-13T10:00:00Z",
  "content": {
    "target": "ARTICLE-VII",
    "action": "add",
    "text": {
      "id": "ARTICLE-VII",
      "name": "Data Retention",
      "sections": [
        {
          "id": "VII.1",
          "title": "Retention Periods",
          "text": "Receipts shall be retained for a minimum of 10 years..."
        }
      ]
    }
  },
  "rationale": "Compliance with emerging EU digital infrastructure regulations requires explicit retention policies.",
  "impact_assessment": {
    "affected_engines": ["all"],
    "backward_compatible": true,
    "migration_required": false
  },
  "status": "deliberation",
  "tags": ["governance", "proposal", "amendment"],
  "root_hash": "blake3:aaa111..."
}
```

### 4.3 Vote Receipt

```json
{
  "type": "gov_vote",
  "vote_id": "VOTE-2025-12-001-sovereign",
  "proposal_id": "PROP-2025-12-001",
  "voter": "did:vm:human:sovereign",
  "voted_at": "2025-12-14T10:00:00Z",
  "vote": "approve",
  "weight": 1.0,
  "comments": "Essential for regulatory compliance.",
  "signature": "z58D...",
  "tags": ["governance", "vote", "approve"],
  "root_hash": "blake3:bbb222..."
}
```

### 4.4 Ratification Receipt

```json
{
  "type": "gov_ratification",
  "ratification_id": "RAT-2025-12-001",
  "proposal_id": "PROP-2025-12-001",
  "ratified_at": "2025-12-14T12:00:00Z",
  "ratified_by": "did:vm:human:sovereign",
  "vote_summary": {
    "approve": 1,
    "reject": 0,
    "abstain": 0
  },
  "quorum_met": true,
  "effective_at": "pending_anchor",
  "constitution_version_before": "1.0.0",
  "constitution_version_after": "1.1.0",
  "signature": "z58D...",
  "tags": ["governance", "ratification", "amendment"],
  "root_hash": "blake3:ccc333..."
}
```

### 4.5 Amendment Receipt

```json
{
  "type": "gov_amendment",
  "amendment_id": "AMEND-2025-12-001",
  "proposal_id": "PROP-2025-12-001",
  "ratification_id": "RAT-2025-12-001",
  "effective_at": "2025-12-14T14:00:00Z",
  "anchor_confirmed_at": "2025-12-14T14:00:00Z",
  "anchor_proof": {
    "backend": "ethereum",
    "tx_hash": "0x123...",
    "block_number": 12345678
  },
  "amendment_type": "add_article",
  "target": "ARTICLE-VII",
  "constitution_hash_before": "blake3:const_v1.0...",
  "constitution_hash_after": "blake3:const_v1.1...",
  "tags": ["governance", "amendment", "effective"],
  "root_hash": "blake3:ddd444..."
}
```

---

## 5. Executive Orders

For operational decisions that don't require full amendment:

### 5.1 Executive Order Receipt

```json
{
  "type": "gov_executive_order",
  "order_id": "EO-2025-12-001",
  "title": "Temporary Rate Limit Increase",
  "issued_by": "did:vm:human:sovereign",
  "issued_at": "2025-12-06T15:00:00Z",
  "authority": "ARTICLE-I.1 (Sovereign Authority)",
  "order_type": "parameter_change",
  "content": {
    "parameter": "guardian.anchor_rate_limit",
    "old_value": "100/day",
    "new_value": "500/day",
    "reason": "Handling increased receipt volume during Q4 compliance push"
  },
  "duration": {
    "type": "temporary",
    "expires_at": "2026-01-01T00:00:00Z"
  },
  "tags": ["governance", "executive-order", "parameter"],
  "root_hash": "blake3:eee555..."
}
```

### 5.2 Emergency Declaration

```json
{
  "type": "gov_executive_order",
  "order_id": "EO-2025-12-002",
  "title": "Security Emergency Declaration",
  "issued_by": "did:vm:human:sovereign",
  "issued_at": "2025-12-06T03:50:00Z",
  "authority": "ARTICLE-VI.1 (Emergency Declaration)",
  "order_type": "emergency",
  "content": {
    "emergency_type": "security_incident",
    "threat_description": "Active intrusion attempt detected on BRICK-02",
    "powers_invoked": [
      "Suspend normal authentication delays",
      "Enable enhanced logging on all nodes",
      "Authorize immediate capability revocation"
    ],
    "incident_reference": "INC-2025-12-001"
  },
  "duration": {
    "type": "emergency",
    "expires_at": "2025-12-09T03:50:00Z",
    "renewable": true
  },
  "tags": ["governance", "executive-order", "emergency", "security"],
  "root_hash": "blake3:fff666..."
}
```

---

## 6. Violation and Enforcement

### 6.1 Violation Detection

Guardian monitors for constitutional violations:

```json
{
  "type": "gov_violation",
  "violation_id": "VIOL-2025-12-001",
  "detected_at": "2025-12-06T16:00:00Z",
  "detected_by": "engine:guardian",
  "violation_type": "unauthorized_action",
  "severity": "high",
  "details": {
    "actor": "did:vm:agent:automation-01",
    "action_attempted": "modify_receipt",
    "receipt_targeted": "receipt:compliance:oracle-answer-4721",
    "rule_violated": "AXIOM-001 (Append-Only Receipts)",
    "action_result": "blocked"
  },
  "evidence": {
    "log_entries": ["..."],
    "request_hash": "blake3:...",
    "stack_trace": "..."
  },
  "tags": ["governance", "violation", "axiom", "blocked"],
  "root_hash": "blake3:ggg777..."
}
```

### 6.2 Enforcement Action

```json
{
  "type": "gov_enforcement",
  "enforcement_id": "ENF-2025-12-001",
  "violation_id": "VIOL-2025-12-001",
  "enforced_at": "2025-12-06T16:05:00Z",
  "enforced_by": "engine:guardian",
  "enforcement_type": "capability_suspension",
  "target": "did:vm:agent:automation-01",
  "action_taken": {
    "capability_suspended": "write",
    "scope": "all_scrolls",
    "duration": "pending_review"
  },
  "authority": "ARTICLE-IV.3 (Due Process) - emergency exception",
  "review_required": true,
  "review_deadline": "2025-12-07T16:05:00Z",
  "tags": ["governance", "enforcement", "suspension"],
  "root_hash": "blake3:hhh888..."
}
```

---

## 7. CLI Commands

```bash
# Constitution
vm-gov constitution show
vm-gov constitution version
vm-gov constitution diff v1.0.0 v1.1.0
vm-gov constitution export --format pdf

# Proposals
vm-gov proposal create --type amendment --file proposal.json
vm-gov proposal list --status deliberation
vm-gov proposal show PROP-2025-12-001
vm-gov proposal comment PROP-2025-12-001 --text "I support this because..."

# Voting
vm-gov vote PROP-2025-12-001 --vote approve --comment "Essential change"
vm-gov vote PROP-2025-12-001 --vote reject --reason "Needs more deliberation"

# Ratification (Sovereign only)
vm-gov ratify PROP-2025-12-001

# Executive Orders
vm-gov order create --type parameter_change --file order.json
vm-gov order list --active
vm-gov order show EO-2025-12-001
vm-gov order revoke EO-2025-12-001

# Emergencies
vm-gov emergency declare --type security_incident --description "..." --incident INC-2025-12-001
vm-gov emergency status
vm-gov emergency extend --hours 24
vm-gov emergency end

# Violations
vm-gov violations list --severity high,critical
vm-gov violations show VIOL-2025-12-001
vm-gov violations review VIOL-2025-12-001 --decision dismiss --reason "False positive"

# Enforcement
vm-gov enforcement list --pending-review
vm-gov enforcement review ENF-2025-12-001 --decision uphold
vm-gov enforcement review ENF-2025-12-001 --decision reverse --reason "Excessive response"
```

---

## 8. Design Gate Checklist

| Question | Governance Answer |
|----------|-------------------|
| Clear entrypoint? | ✅ CLI (`vm-gov`), Portal routes |
| Contract produced? | ✅ Proposal documents |
| State object? | ✅ Constitution + amendment state |
| Receipts emitted? | ✅ Seven receipt types |
| Append-only JSONL? | ✅ `receipts/governance/governance_events.jsonl` |
| Merkle root? | ✅ `ROOT.governance.txt` |
| Guardian anchor path? | ✅ Governance root included in ProofChain |
| Query tool? | ✅ `vm-gov` CLI |

---

## 9. Constitutional Hash Chain

The Constitution itself is version-controlled with a hash chain:

```json
{
  "constitution_versions": [
    {
      "version": "1.0.0",
      "effective_at": "2025-06-01T00:00:00Z",
      "hash": "blake3:const_v1.0_abc123...",
      "previous_hash": null,
      "amendment_id": null
    },
    {
      "version": "1.1.0",
      "effective_at": "2025-12-14T14:00:00Z",
      "hash": "blake3:const_v1.1_def456...",
      "previous_hash": "blake3:const_v1.0_abc123...",
      "amendment_id": "AMEND-2025-12-001"
    }
  ]
}
```

This creates an immutable chain of constitutional states — you can always verify what the rules were at any point in time.