vaultsovereign/vm-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initialize repository snapshot

Browse Source
This commit is contained in:
Vault Sovereign
2025-12-27 00:10:32 +00:00
commit 110d644e10
281 changed files with 40331 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

554
docs/VAULTMESH-MESH-ENGINE.md Normal file
View File

@@ -0,0 +1,554 @@
# 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