# VaultMesh Federation & Governance Protocols

## Federation Protocol

### Trust Establishment Flow

```
┌──────────────┐                    ┌──────────────┐
│   MESH-A     │                    │   MESH-B     │
│   (Dublin)   │                    │   (Berlin)   │
└──────┬───────┘                    └──────┬───────┘
       │                                   │
       │  1. Discovery                     │
       │   GET /federation/discovery       │
       │──────────────────────────────────►│
       │                                   │
       │  2. Proposal                      │
       │   POST /federation/proposals      │
       │──────────────────────────────────►│
       │                                   │
       │  3. Counter/Accept                │
       │◄──────────────────────────────────│
       │                                   │
       │  4. Mutual Signature              │
       │◄─────────────────────────────────►│
       │                                   │
       │  5. Begin Witness Cycle           │
       │◄─────────────────────────────────►│
       │                                   │
```

### Trust Levels

| Level | Name | Capabilities |
|-------|------|--------------|
| 0 | `isolated` | No federation |
| 1 | `observe` | Read-only witness, public receipts only |
| 2 | `verify` | Mutual verification, receipt sampling |
| 3 | `attest` | Cross-attestation, shared roots |
| 4 | `integrate` | Shared scrolls, joint governance |

### Discovery Record

```json
{
  "mesh_id": "did:vm:mesh:vaultmesh-dublin",
  "display_name": "VaultMesh Dublin",
  "endpoints": {
    "federation": "https://federation.vaultmesh-dublin.io",
    "verification": "https://verify.vaultmesh-dublin.io"
  },
  "public_key": "ed25519:z6Mk...",
  "scrolls_available": ["Compliance", "Drills"],
  "trust_policy": {
    "accepts_proposals": true,
    "min_trust_level": 1,
    "requires_mutual": true
  },
  "attestations": []
}
```

### Trust Proposal

```json
{
  "proposal_id": "fed-proposal-2025-12-06-001",
  "proposer": "did:vm:mesh:vaultmesh-dublin",
  "target": "did:vm:mesh:vaultmesh-berlin",
  "proposed_at": "2025-12-06T10:00:00Z",
  "expires_at": "2025-12-13T10:00:00Z",
  "proposed_trust_level": 2,
  "proposed_terms": {
    "scrolls_to_share": ["Compliance"],
    "verification_frequency": "hourly",
    "retention_period_days": 365,
    "data_jurisdiction": "EU",
    "audit_rights": true
  },
  "proposer_attestations": {
    "identity_proof": "...",
    "compliance_credentials": ["ISO27001", "SOC2"]
  },
  "signature": "z58D..."
}
```

### Federation Agreement

```json
{
  "agreement_id": "fed-agreement-2025-12-06-001",
  "parties": [
    "did:vm:mesh:vaultmesh-dublin",
    "did:vm:mesh:vaultmesh-berlin"
  ],
  "established_at": "2025-12-06T16:00:00Z",
  "trust_level": 2,
  "terms": {
    "scrolls_shared": ["Compliance", "Drills"],
    "verification_frequency": "daily",
    "retention_period_days": 180,
    "data_jurisdiction": "EU",
    "audit_rights": true,
    "dispute_resolution": "arbitration_zurich"
  },
  "key_exchange": {
    "dublin_federation_key": "ed25519:z6MkDublin...",
    "berlin_federation_key": "ed25519:z6MkBerlin..."
  },
  "signatures": {
    "did:vm:mesh:vaultmesh-dublin": {
      "signed_at": "2025-12-06T15:30:00Z",
      "signature": "z58D..."
    },
    "did:vm:mesh:vaultmesh-berlin": {
      "signed_at": "2025-12-06T16:00:00Z",
      "signature": "z47C..."
    }
  },
  "agreement_hash": "blake3:abc123..."
}
```

### Witness Protocol

```
Anchor Completes → Notify Peer → Peer Verifies → Witness Receipt
```

**Witness Receipt**:
```json
{
  "type": "fed_witness_event",
  "witness_id": "witness-2025-12-06-001",
  "witnessed_mesh": "did:vm:mesh:vaultmesh-dublin",
  "witnessing_mesh": "did:vm:mesh:vaultmesh-berlin",
  "timestamp": "2025-12-06T12:05:00Z",
  "scroll": "Compliance",
  "witnessed_root": "blake3:aaa111...",
  "witnessed_anchor": {
    "backend": "ethereum",
    "tx_hash": "0x123...",
    "block_number": 12345678
  },
  "verification_method": "anchor_proof_validation",
  "verification_result": "verified",
  "samples_checked": 5,
  "discrepancies": [],
  "witness_signature": "z47C..."
}
```

### Cross-Anchor

At trust level 3+, meshes include each other's roots:

```json
{
  "type": "fed_cross_anchor",
  "anchoring_mesh": "did:vm:mesh:vaultmesh-berlin",
  "anchored_mesh": "did:vm:mesh:vaultmesh-dublin",
  "dublin_roots_included": {
    "Compliance": "blake3:aaa111...",
    "Drills": "blake3:bbb222..."
  },
  "combined_root": "blake3:ccc333...",
  "anchor_proof": {
    "backend": "bitcoin",
    "tx_hash": "abc123..."
  }
}
```

### Federation API Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/federation/discovery` | GET | Get mesh discovery record |
| `/federation/proposals` | POST | Submit trust proposal |
| `/federation/proposals/{id}` | GET, PUT | View/respond to proposal |
| `/federation/agreements` | GET | List active agreements |
| `/federation/agreements/{id}` | GET, DELETE | View/revoke agreement |
| `/federation/notify` | POST | Notify of new anchor |
| `/federation/witness` | POST | Submit witness attestation |
| `/federation/roots` | GET | Get current Merkle roots |
| `/federation/receipts/{scroll}` | GET | Fetch receipt samples |
| `/federation/verify` | POST | Request receipt verification |

### CLI Commands

```bash
# Discovery
vm-federation discover --mesh vaultmesh-berlin.io
vm-federation list-known

# Proposals
vm-federation propose \
  --target did:vm:mesh:vaultmesh-berlin \
  --trust-level 2 \
  --scrolls Compliance,Drills

vm-federation proposals list
vm-federation proposals accept fed-proposal-001
vm-federation proposals reject fed-proposal-001 --reason "..."

# Agreements
vm-federation agreements list
vm-federation agreements revoke fed-agreement-001 --notice-days 30

# Verification
vm-federation verify --mesh vaultmesh-berlin --scroll Compliance
vm-federation witness-history --mesh vaultmesh-berlin --last 30d

# Status
vm-federation status
vm-federation health --all-peers
```

---

## Constitutional Governance

### Hierarchy

```
┌─────────────────────────────────────────────────────────────────┐
│  IMMUTABLE AXIOMS                                               │
│  (Cannot be changed, ever)                                      │
└─────────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  CONSTITUTIONAL ARTICLES                                        │
│  (Amendable with supermajority + ratification)                  │
└─────────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  STATUTORY RULES                                                │
│  (Changeable with standard procedures)                          │
└─────────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  EXECUTIVE ORDERS                                               │
│  (Issued by authorized actors)                                  │
└─────────────────────────────────────────────────────────────────┘
```

### Immutable Axioms

| ID | Name | Statement |
|----|------|-----------|
| AXIOM-001 | Append-Only Receipts | Receipts, once written, shall never be modified or deleted |
| AXIOM-002 | Cryptographic Integrity | All receipts include cryptographic hashes |
| AXIOM-003 | Universal Receipting | All significant changes produce receipts |
| AXIOM-004 | Constitutional Supremacy | No action may violate the Constitution |
| AXIOM-005 | Axiom Immutability | These axioms cannot be amended |

### Constitutional Articles

| Article | Name | Content |
|---------|------|---------|
| I | Governance Structure | Sovereign authority, engine authorities, agent delegation |
| II | Amendment Procedure | Proposal, deliberation, ratification |
| III | Engine Governance | Engine registry, boundaries, lifecycle |
| IV | Rights and Protections | Audit rights, data sovereignty, due process |
| V | Federation | Authority, limits, termination |
| VI | Emergency Powers | Declaration, powers, duration |

### Amendment Workflow

```
PROPOSAL → DELIBERATION (7+ days) → VOTING → RATIFICATION → ACTIVATION
                                          ↘ REJECTED → Archive
```

### 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": [...]
    }
  },
  "rationale": "Compliance with EU regulations",
  "status": "deliberation"
}
```

### 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 compliance",
  "signature": "z58D..."
}
```

### 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,
  "constitution_version_before": "1.0.0",
  "constitution_version_after": "1.1.0"
}
```

### Amendment Receipt

```json
{
  "type": "gov_amendment",
  "amendment_id": "AMEND-2025-12-001",
  "proposal_id": "PROP-2025-12-001",
  "effective_at": "2025-12-14T14:00:00Z",
  "anchor_proof": {
    "backend": "ethereum",
    "tx_hash": "0x123..."
  },
  "constitution_hash_before": "blake3:const_v1.0...",
  "constitution_hash_after": "blake3:const_v1.1..."
}
```

### Executive Orders

For operational decisions without full amendment:

```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",
  "order_type": "parameter_change",
  "content": {
    "parameter": "guardian.anchor_rate_limit",
    "old_value": "100/day",
    "new_value": "500/day"
  },
  "duration": {
    "type": "temporary",
    "expires_at": "2026-01-01T00:00:00Z"
  }
}
```

### Emergency Declaration

```json
{
  "type": "gov_executive_order",
  "order_id": "EO-2025-12-002",
  "title": "Security Emergency",
  "issued_by": "did:vm:human:sovereign",
  "authority": "ARTICLE-VI.1",
  "order_type": "emergency",
  "content": {
    "emergency_type": "security_incident",
    "threat_description": "Active intrusion on BRICK-02",
    "powers_invoked": [
      "Suspend authentication delays",
      "Enhanced logging",
      "Immediate capability revocation"
    ]
  },
  "duration": {
    "type": "emergency",
    "expires_at": "2025-12-09T03:50:00Z",
    "renewable": true
  }
}
```

### Violation Detection

```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",
    "rule_violated": "AXIOM-001",
    "action_result": "blocked"
  },
  "evidence": {
    "log_entries": ["..."],
    "request_hash": "blake3:..."
  }
}
```

### 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",
  "enforcement_type": "capability_suspension",
  "target": "did:vm:agent:automation-01",
  "action_taken": {
    "capability_suspended": "write",
    "scope": "all_scrolls",
    "duration": "pending_review"
  },
  "review_required": true,
  "review_deadline": "2025-12-07T16:05:00Z"
}
```

### CLI Commands

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

# Proposals
vm-gov proposal create --type amendment --file proposal.json
vm-gov proposal list --status deliberation
vm-gov proposal show PROP-2025-12-001

# Voting
vm-gov vote PROP-2025-12-001 --vote approve
vm-gov vote PROP-2025-12-001 --vote reject --reason "..."

# Ratification
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 revoke EO-2025-12-001

# Emergencies
vm-gov emergency declare --type security_incident --description "..."
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 review VIOL-2025-12-001 --decision dismiss

# Enforcement
vm-gov enforcement list --pending-review
vm-gov enforcement review ENF-2025-12-001 --decision uphold
```

---

## Engine Registry

All engines must be registered in the Constitution:

```json
{
  "registered_engines": [
    {
      "engine_id": "engine:drills",
      "name": "Security Drills",
      "scroll": "Drills",
      "authority": "Security training and exercise management",
      "status": "active"
    },
    {
      "engine_id": "engine:oracle",
      "name": "Compliance Oracle",
      "scroll": "Compliance",
      "authority": "Compliance question answering",
      "status": "active"
    },
    {
      "engine_id": "engine:guardian",
      "name": "Guardian",
      "scroll": "Guardian",
      "authority": "Anchoring and sentinel",
      "status": "active"
    },
    {
      "engine_id": "engine:treasury",
      "name": "Treasury",
      "scroll": "Treasury",
      "authority": "Financial tracking",
      "status": "active"
    },
    {
      "engine_id": "engine:mesh",
      "name": "Mesh",
      "scroll": "Mesh",
      "authority": "Topology management",
      "status": "active"
    },
    {
      "engine_id": "engine:offsec",
      "name": "OffSec",
      "scroll": "OffSec",
      "authority": "Security operations",
      "status": "active"
    },
    {
      "engine_id": "engine:identity",
      "name": "Identity",
      "scroll": "Identity",
      "authority": "DID and capability management",
      "status": "active"
    },
    {
      "engine_id": "engine:observability",
      "name": "Observability",
      "scroll": "Observability",
      "authority": "Telemetry monitoring",
      "status": "active"
    },
    {
      "engine_id": "engine:automation",
      "name": "Automation",
      "scroll": "Automation",
      "authority": "Workflow execution",
      "status": "active"
    },
    {
      "engine_id": "engine:psi",
      "name": "Ψ-Field",
      "scroll": "PsiField",
      "authority": "Consciousness tracking",
      "status": "active"
    },
    {
      "engine_id": "engine:federation",
      "name": "Federation",
      "scroll": "Federation",
      "authority": "Cross-mesh trust",
      "status": "active"
    },
    {
      "engine_id": "engine:governance",
      "name": "Governance",
      "scroll": "Governance",
      "authority": "Constitutional enforcement",
      "status": "active"
    }
  ]
}
```

### Adding New Engines

New engines require constitutional amendment:

1. Draft proposal with engine specification
2. 7-day deliberation period
3. Sovereign approval
4. Anchor confirmation activates engine

```bash
vm-gov proposal create \
  --type add_engine \
  --engine-id engine:analytics \
  --name "Analytics" \
  --scroll Analytics \
  --authority "Data analysis and insights"
```