# VAULTMESH-MESH-ENGINE.md

**Civilization Ledger Federation Primitive**

> *Nodes that anchor together, survive together.*

Mesh is VaultMesh's topology memory — tracking how nodes discover each other, establish trust, share capabilities, and evolve their federation relationships over time. Every topology change becomes evidence.

---

## 1. Scroll Definition

| Property              | Value                                                                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Scroll Name**       | `Mesh`                                                                                                                                     |
| **JSONL Path**        | `receipts/mesh/mesh_events.jsonl`                                                                                                          |
| **Root File**         | `ROOT.mesh.txt`                                                                                                                            |
| **Receipt Types**     | `mesh_node_join`, `mesh_node_leave`, `mesh_route_change`, `mesh_capability_grant`, `mesh_capability_revoke`, `mesh_topology_snapshot`      |

---

## 2. Core Concepts

### 2.1 Nodes

A **node** is any VaultMesh-aware endpoint that participates in the federation.

```json
{
  "node_id": "did:vm:node:brick-01",
  "display_name": "BRICK-01 (Dublin Primary)",
  "node_type": "infrastructure",
  "endpoints": {
    "portal": "https://brick-01.vaultmesh.local:8443",
    "wireguard": "10.77.1.1",
    "tailscale": "brick-01.tail.net"
  },
  "public_key": "ed25519:abc123...",
  "capabilities": ["anchor", "storage", "compute", "oracle"],
  "status": "active",
  "joined_at": "2025-06-15T00:00:00Z",
  "last_seen": "2025-12-06T14:30:00Z",
  "tags": ["production", "eu-west", "akash"]
}
```

**Node types**:

* `infrastructure` — BRICK servers, compute nodes
* `edge` — mobile devices, sovereign phones, field endpoints
* `oracle` — compliance oracle instances
* `guardian` — dedicated anchor/sentinel nodes
* `external` — federated nodes from other VaultMesh deployments

### 2.2 Routes

A **route** defines how traffic flows between nodes or segments.

```json
{
  "route_id": "route-brick01-to-brick02",
  "source": "did:vm:node:brick-01",
  "destination": "did:vm:node:brick-02",
  "transport": "wireguard",
  "priority": 1,
  "status": "active",
  "latency_ms": 12,
  "established_at": "2025-06-20T00:00:00Z"
}
```

Routes can be:

* **Direct**: Node-to-node (WireGuard, Tailscale)
* **Relayed**: Through a gateway node
* **Redundant**: Multiple paths with failover priority

### 2.3 Capabilities

**Capabilities** are the trust primitives — what a node is permitted to do within the federation.

```json
{
  "capability_id": "cap:brick-01:anchor:2025",
  "node_id": "did:vm:node:brick-01",
  "capability": "anchor",
  "scope": "global",
  "granted_by": "did:vm:node:portal-01",
  "granted_at": "2025-06-15T00:00:00Z",
  "expires_at": "2026-06-15T00:00:00Z",
  "constraints": {
    "max_anchor_rate": "100/day",
    "allowed_scrolls": ["*"]
  }
}
```

Standard capabilities:

* `anchor` — can submit roots to anchor backends
* `storage` — can store receipts and artifacts
* `compute` — can execute drills, run agents
* `oracle` — can issue compliance answers
* `admin` — can grant/revoke capabilities to other nodes
* `federate` — can establish trust with external meshes

### 2.4 Topology Snapshots

Periodic **snapshots** capture the full mesh state — useful for auditing, disaster recovery, and proving historical topology.

---

## 3. Mapping to Eternal Pattern

### 3.1 Experience Layer (L1)

**CLI** (`vm-mesh`):

```bash
# Node operations
vm-mesh node list
vm-mesh node show brick-01
vm-mesh node join --config node-manifest.json
vm-mesh node leave --node brick-02 --reason "decommissioned"

# Route operations
vm-mesh route list
vm-mesh route add --from brick-01 --to brick-03 --transport tailscale
vm-mesh route test --route route-brick01-to-brick02

# Capability operations
vm-mesh capability list --node brick-01
vm-mesh capability grant --node brick-02 --capability oracle --expires 2026-01-01
vm-mesh capability revoke --node brick-02 --capability anchor --reason "security incident"

# Topology
vm-mesh topology show
vm-mesh topology snapshot --output snapshots/2025-12-06.json
vm-mesh topology diff --from snapshots/2025-11-01.json --to snapshots/2025-12-06.json

# Health
vm-mesh health --full
vm-mesh ping --all
```

**MCP Tools**:

* `mesh_node_status` — get node details and health
* `mesh_list_nodes` — enumerate active nodes
* `mesh_topology_summary` — current topology overview
* `mesh_capability_check` — verify if node has capability
* `mesh_route_health` — check route latency and status

**Portal HTTP**:

* `GET /mesh/nodes` — list nodes
* `GET /mesh/nodes/{node_id}` — node details
* `POST /mesh/nodes/join` — register new node
* `POST /mesh/nodes/{node_id}/leave` — deregister node
* `GET /mesh/routes` — list routes
* `POST /mesh/routes` — add route
* `GET /mesh/capabilities/{node_id}` — node capabilities
* `POST /mesh/capabilities/grant` — grant capability
* `POST /mesh/capabilities/revoke` — revoke capability
* `GET /mesh/topology` — current topology
* `POST /mesh/topology/snapshot` — create snapshot

---

### 3.2 Engine Layer (L2)

#### Step 1 — Plan → `mesh_change_contract.json`

For simple operations (single node join, route add), the contract is implicit.

For coordinated topology changes, an explicit contract:

```json
{
  "change_id": "mesh-change-2025-12-06-001",
  "title": "Add BRICK-03 to Dublin Cluster",
  "initiated_by": "did:vm:node:portal-01",
  "initiated_at": "2025-12-06T11:00:00Z",
  "change_type": "node_expansion",
  "operations": [
    {
      "op_id": "op-001",
      "operation": "node_join",
      "target": "did:vm:node:brick-03",
      "config": {
        "display_name": "BRICK-03 (Dublin Secondary)",
        "node_type": "infrastructure",
        "endpoints": {
          "portal": "https://brick-03.vaultmesh.local:8443",
          "wireguard": "10.77.1.3"
        },
        "public_key": "ed25519:def456..."
      }
    },
    {
      "op_id": "op-002",
      "operation": "route_add",
      "config": {
        "source": "did:vm:node:brick-01",
        "destination": "did:vm:node:brick-03",
        "transport": "wireguard"
      }
    },
    {
      "op_id": "op-003",
      "operation": "route_add",
      "config": {
        "source": "did:vm:node:brick-02",
        "destination": "did:vm:node:brick-03",
        "transport": "wireguard"
      }
    },
    {
      "op_id": "op-004",
      "operation": "capability_grant",
      "config": {
        "node_id": "did:vm:node:brick-03",
        "capability": "storage",
        "scope": "local",
        "expires_at": "2026-12-06T00:00:00Z"
      }
    }
  ],
  "requires_approval": ["portal-01"],
  "rollback_on_failure": true
}
```

#### Step 2 — Execute → `mesh_change_state.json`

```json
{
  "change_id": "mesh-change-2025-12-06-001",
  "status": "in_progress",
  "created_at": "2025-12-06T11:00:00Z",
  "updated_at": "2025-12-06T11:05:00Z",
  "operations": [
    {
      "op_id": "op-001",
      "status": "completed",
      "completed_at": "2025-12-06T11:02:00Z",
      "result": {
        "node_registered": true,
        "handshake_verified": true
      }
    },
    {
      "op_id": "op-002",
      "status": "completed",
      "completed_at": "2025-12-06T11:03:00Z",
      "result": {
        "route_established": true,
        "latency_ms": 8
      }
    },
    {
      "op_id": "op-003",
      "status": "in_progress",
      "started_at": "2025-12-06T11:04:00Z"
    },
    {
      "op_id": "op-004",
      "status": "pending"
    }
  ],
  "topology_before_hash": "blake3:aaa111...",
  "approvals": {
    "portal-01": {
      "approved_at": "2025-12-06T11:01:00Z",
      "signature": "ed25519:..."
    }
  }
}
```

**Status transitions**:

```
draft → pending_approval → in_progress → completed
                                       ↘ partial_failure → rollback → rolled_back
                                       ↘ failed → rollback → rolled_back
```

#### Step 3 — Seal → Receipts

Each operation in a change produces its own receipt, plus a summary receipt for coordinated changes.

**Node Join Receipt**:

```json
{
  "type": "mesh_node_join",
  "node_id": "did:vm:node:brick-03",
  "display_name": "BRICK-03 (Dublin Secondary)",
  "node_type": "infrastructure",
  "timestamp": "2025-12-06T11:02:00Z",
  "initiated_by": "did:vm:node:portal-01",
  "change_id": "mesh-change-2025-12-06-001",
  "endpoints_hash": "blake3:...",
  "public_key_fingerprint": "SHA256:...",
  "tags": ["mesh", "node", "join", "infrastructure"],
  "root_hash": "blake3:bbb222..."
}
```

**Route Change Receipt**:

```json
{
  "type": "mesh_route_change",
  "route_id": "route-brick01-to-brick03",
  "operation": "add",
  "source": "did:vm:node:brick-01",
  "destination": "did:vm:node:brick-03",
  "transport": "wireguard",
  "timestamp": "2025-12-06T11:03:00Z",
  "initiated_by": "did:vm:node:portal-01",
  "change_id": "mesh-change-2025-12-06-001",
  "latency_ms": 8,
  "tags": ["mesh", "route", "add"],
  "root_hash": "blake3:ccc333..."
}
```

**Capability Grant Receipt**:

```json
{
  "type": "mesh_capability_grant",
  "capability_id": "cap:brick-03:storage:2025",
  "node_id": "did:vm:node:brick-03",
  "capability": "storage",
  "scope": "local",
  "granted_by": "did:vm:node:portal-01",
  "timestamp": "2025-12-06T11:06:00Z",
  "expires_at": "2026-12-06T00:00:00Z",
  "change_id": "mesh-change-2025-12-06-001",
  "tags": ["mesh", "capability", "grant", "storage"],
  "root_hash": "blake3:ddd444..."
}
```

**Topology Snapshot Receipt** (periodic):

```json
{
  "type": "mesh_topology_snapshot",
  "snapshot_id": "snapshot-2025-12-06-001",
  "timestamp": "2025-12-06T12:00:00Z",
  "node_count": 5,
  "route_count": 12,
  "capability_count": 23,
  "nodes": ["brick-01", "brick-02", "brick-03", "portal-01", "oracle-01"],
  "topology_hash": "blake3:eee555...",
  "snapshot_path": "snapshots/mesh/2025-12-06-001.json",
  "tags": ["mesh", "snapshot", "topology"],
  "root_hash": "blake3:fff666..."
}
```

---

### 3.3 Ledger Layer (L3)

**Receipt Types**:

| Type                       | When Emitted                      |
| -------------------------- | --------------------------------- |
| `mesh_node_join`           | Node registered in mesh           |
| `mesh_node_leave`          | Node deregistered                 |
| `mesh_route_change`        | Route added, removed, or modified |
| `mesh_capability_grant`    | Capability granted to node        |
| `mesh_capability_revoke`   | Capability revoked from node      |
| `mesh_topology_snapshot`   | Periodic full topology capture    |

**Merkle Coverage**:

* All receipts append to `receipts/mesh/mesh_events.jsonl`
* `ROOT.mesh.txt` updated after each append
* Guardian anchors Mesh root in anchor cycles

---

## 4. Query Interface

`mesh_query_events.py`:

```bash
# All events for a node
vm-mesh query --node brick-01

# Events by type
vm-mesh query --type node_join
vm-mesh query --type capability_grant

# Date range
vm-mesh query --from 2025-11-01 --to 2025-12-01

# By change ID (coordinated changes)
vm-mesh query --change-id mesh-change-2025-12-06-001

# Capability history for a node
vm-mesh query --node brick-02 --type capability_grant,capability_revoke

# Export topology history
vm-mesh query --type topology_snapshot --format json > topology_history.json
```

**Topology Diff Tool**:

```bash
# Compare two snapshots
vm-mesh topology diff \
  --from snapshots/mesh/2025-11-01.json \
  --to snapshots/mesh/2025-12-06.json

# Output:
# + node: brick-03 (joined)
# + route: brick-01 → brick-03
# + route: brick-02 → brick-03
# + capability: brick-03:storage
# ~ route: brick-01 → brick-02 (latency: 15ms → 12ms)
```

---

## 5. Design Gate Checklist

| Question              | Mesh Answer                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------- |
| Clear entrypoint?     | ✅ CLI (`vm-mesh`), MCP tools, Portal HTTP                                               |
| Contract produced?    | ✅ `mesh_change_contract.json` (explicit for coordinated changes, implicit for single ops) |
| State object?         | ✅ `mesh_change_state.json` tracking operation progress                                   |
| Receipts emitted?     | ✅ Six receipt types covering all topology events                                         |
| Append-only JSONL?    | ✅ `receipts/mesh/mesh_events.jsonl`                                                      |
| Merkle root?          | ✅ `ROOT.mesh.txt`                                                                        |
| Guardian anchor path? | ✅ Mesh root included in ProofChain                                                       |
| Query tool?           | ✅ `mesh_query_events.py` + topology diff                                                 |

---

## 6. Mesh Health & Consensus

### 6.1 Heartbeat Protocol

Nodes emit periodic heartbeats to prove liveness:

```json
{
  "type": "heartbeat",
  "node_id": "did:vm:node:brick-01",
  "timestamp": "2025-12-06T14:30:00Z",
  "sequence": 847293,
  "load": {
    "cpu_percent": 23,
    "memory_percent": 67,
    "disk_percent": 45
  },
  "routes_healthy": 4,
  "routes_degraded": 0
}
```

Heartbeats are **not** receipted individually (too high volume), but:

* Aggregated into daily health summaries
* Missed heartbeats trigger alerts
* Prolonged absence → automatic `mesh_node_leave` with `reason: "timeout"`

### 6.2 Quorum Requirements

Critical mesh operations require quorum:

| Operation                       | Quorum                            |
| ------------------------------- | --------------------------------- |
| Node join                       | 1 admin node                      |
| Node forced leave               | 2 admin nodes                     |
| Capability grant (global scope) | 2 admin nodes                     |
| Capability revoke               | 1 admin node (immediate security) |
| Federation trust establishment  | All admin nodes                   |

---

## 7. Federation (Multi-Mesh)

When VaultMesh instances need to federate (e.g., partner organizations, geographic regions):

### 7.1 Trust Establishment

```json
{
  "type": "mesh_federation_trust",
  "local_mesh": "did:vm:mesh:vaultmesh-dublin",
  "remote_mesh": "did:vm:mesh:partner-berlin",
  "trust_level": "limited",
  "established_at": "2025-12-06T15:00:00Z",
  "expires_at": "2026-12-06T00:00:00Z",
  "shared_capabilities": ["oracle_query", "receipt_verify"],
  "gateway_node": "did:vm:node:portal-01",
  "remote_gateway": "did:vm:node:partner-gateway-01",
  "trust_anchor": "blake3:ggg777..."
}
```

**Trust levels**:

* `isolated` — no cross-mesh communication
* `limited` — specific capabilities only (e.g., query each other's Oracle)
* `reciprocal` — mutual receipt verification, shared anchoring
* `full` — complete federation (rare, high-trust scenarios)

### 7.2 Cross-Mesh Receipts

When a federated mesh verifies or references receipts:

```json
{
  "type": "mesh_cross_verify",
  "local_receipt": "receipt:treasury:settle-2025-12-06-001",
  "remote_mesh": "did:vm:mesh:partner-berlin",
  "verified_by": "did:vm:node:partner-oracle-01",
  "verification_timestamp": "2025-12-06T16:00:00Z",
  "verification_result": "valid",
  "remote_root_at_verification": "blake3:hhh888..."
}
```

---

## 8. Integration Points

| System         | Integration                                                                               |
| -------------- | ----------------------------------------------------------------------------------------- |
| **Guardian**   | Anchors `ROOT.mesh.txt`; alerts on unexpected topology changes                            |
| **Treasury**   | Node join can auto-create Treasury accounts; node leave triggers account closure workflow |
| **Oracle**     | Can query Mesh for node capabilities ("Does BRICK-02 have anchor capability?")            |
| **Drills**     | Multi-node drills require Mesh to verify all participants are active and routable         |
| **OffSec**     | Security incidents can trigger emergency capability revocations via Mesh                  |

---

## 9. Future Extensions

* **Auto-discovery**: Nodes find each other via mDNS/DHT in local networks
* **Geographic awareness**: Route optimization based on node locations
* **Bandwidth metering**: Track data flow between nodes for Treasury billing
* **Mesh visualization**: Real-time topology graph in Portal UI
* **Chaos testing**: Controlled route failures to test resilience
* **Zero-trust verification**: Continuous capability re-verification