908 lines
27 KiB
Markdown
908 lines
27 KiB
Markdown
# VAULTMESH-AUTOMATION-ENGINE.md
|
|
|
|
**Civilization Ledger Workflow Primitive**
|
|
|
|
> *Every workflow has a contract. Every execution has a receipt.*
|
|
|
|
Automation is VaultMesh's orchestration layer — managing n8n workflows, scheduled jobs, event-driven triggers, and multi-step processes with complete audit trails and cryptographic evidence of execution.
|
|
|
|
---
|
|
|
|
## 1. Scroll Definition
|
|
|
|
| Property | Value |
|
|
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **Scroll Name** | `Automation` |
|
|
| **JSONL Path** | `receipts/automation/automation_events.jsonl` |
|
|
| **Root File** | `ROOT.automation.txt` |
|
|
| **Receipt Types** | `auto_workflow_register`, `auto_workflow_execute`, `auto_workflow_complete`, `auto_schedule_create`, `auto_trigger_fire`, `auto_approval_request`, `auto_approval_decision` |
|
|
|
|
---
|
|
|
|
## 2. Core Concepts
|
|
|
|
### 2.1 Workflows
|
|
|
|
A **workflow** is a defined sequence of automated steps that can be triggered manually, on schedule, or by events.
|
|
|
|
```json
|
|
{
|
|
"workflow_id": "wf:daily-compliance-check",
|
|
"name": "Daily Compliance Check",
|
|
"description": "Run Oracle compliance queries and alert on gaps",
|
|
"version": 3,
|
|
"status": "active",
|
|
"created_at": "2025-10-01T00:00:00Z",
|
|
"updated_at": "2025-12-01T00:00:00Z",
|
|
"created_by": "did:vm:user:sovereign",
|
|
"trigger": {
|
|
"type": "schedule",
|
|
"cron": "0 6 * * *",
|
|
"timezone": "Europe/Dublin"
|
|
},
|
|
"steps": [
|
|
{
|
|
"step_id": "step-1",
|
|
"name": "Query Oracle for GDPR compliance",
|
|
"type": "mcp_tool",
|
|
"tool": "oracle_compliance_answer",
|
|
"params": {
|
|
"question": "What is our current GDPR compliance status?",
|
|
"frameworks": ["GDPR"]
|
|
}
|
|
},
|
|
{
|
|
"step_id": "step-2",
|
|
"name": "Query Oracle for AI Act compliance",
|
|
"type": "mcp_tool",
|
|
"tool": "oracle_compliance_answer",
|
|
"params": {
|
|
"question": "What is our current EU AI Act compliance status?",
|
|
"frameworks": ["EU_AI_ACT"]
|
|
}
|
|
},
|
|
{
|
|
"step_id": "step-3",
|
|
"name": "Analyze gaps",
|
|
"type": "condition",
|
|
"condition": "steps['step-1'].result.gaps.length > 0 OR steps['step-2'].result.gaps.length > 0",
|
|
"on_true": "step-4",
|
|
"on_false": "step-5"
|
|
},
|
|
{
|
|
"step_id": "step-4",
|
|
"name": "Alert on compliance gaps",
|
|
"type": "notification",
|
|
"channels": ["slack:compliance-alerts", "email:compliance-team"],
|
|
"template": "compliance_gap_alert"
|
|
},
|
|
{
|
|
"step_id": "step-5",
|
|
"name": "Log success",
|
|
"type": "log",
|
|
"level": "info",
|
|
"message": "Daily compliance check passed"
|
|
}
|
|
],
|
|
"error_handling": {
|
|
"on_step_failure": "continue",
|
|
"max_retries": 3,
|
|
"retry_delay": "5m",
|
|
"notify_on_failure": ["slack:ops-alerts"]
|
|
},
|
|
"metadata": {
|
|
"category": "compliance",
|
|
"tags": ["daily", "gdpr", "ai-act", "oracle"],
|
|
"owner": "compliance-team"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Workflow types**:
|
|
- `scheduled` — cron-based execution
|
|
- `event_triggered` — fires on system events
|
|
- `manual` — operator-initiated
|
|
- `webhook` — external HTTP triggers
|
|
- `chained` — triggered by other workflow completion
|
|
|
|
### 2.2 Executions
|
|
|
|
An **execution** is a single run of a workflow with full context and results.
|
|
|
|
```json
|
|
{
|
|
"execution_id": "exec-2025-12-06-001",
|
|
"workflow_id": "wf:daily-compliance-check",
|
|
"workflow_version": 3,
|
|
"status": "completed",
|
|
"triggered_by": "schedule",
|
|
"triggered_at": "2025-12-06T06:00:00Z",
|
|
"started_at": "2025-12-06T06:00:01Z",
|
|
"completed_at": "2025-12-06T06:02:34Z",
|
|
"duration_ms": 153000,
|
|
"steps": [
|
|
{
|
|
"step_id": "step-1",
|
|
"status": "completed",
|
|
"started_at": "2025-12-06T06:00:01Z",
|
|
"completed_at": "2025-12-06T06:01:15Z",
|
|
"duration_ms": 74000,
|
|
"result": {
|
|
"compliance_score": 0.94,
|
|
"gaps": ["Missing DPO appointment documentation"]
|
|
}
|
|
},
|
|
{
|
|
"step_id": "step-2",
|
|
"status": "completed",
|
|
"started_at": "2025-12-06T06:01:15Z",
|
|
"completed_at": "2025-12-06T06:02:20Z",
|
|
"duration_ms": 65000,
|
|
"result": {
|
|
"compliance_score": 0.87,
|
|
"gaps": ["Risk assessment incomplete for high-risk AI system"]
|
|
}
|
|
},
|
|
{
|
|
"step_id": "step-3",
|
|
"status": "completed",
|
|
"result": {"condition_result": true, "next_step": "step-4"}
|
|
},
|
|
{
|
|
"step_id": "step-4",
|
|
"status": "completed",
|
|
"started_at": "2025-12-06T06:02:21Z",
|
|
"completed_at": "2025-12-06T06:02:34Z",
|
|
"result": {
|
|
"notifications_sent": ["slack:compliance-alerts", "email:compliance-team"]
|
|
}
|
|
}
|
|
],
|
|
"input": {},
|
|
"output": {
|
|
"gdpr_score": 0.94,
|
|
"ai_act_score": 0.87,
|
|
"total_gaps": 2,
|
|
"alert_sent": true
|
|
},
|
|
"context": {
|
|
"node": "did:vm:node:brick-01",
|
|
"environment": "production"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.3 Schedules
|
|
|
|
**Schedules** define when workflows should run automatically.
|
|
|
|
```json
|
|
{
|
|
"schedule_id": "sched:daily-compliance",
|
|
"workflow_id": "wf:daily-compliance-check",
|
|
"cron": "0 6 * * *",
|
|
"timezone": "Europe/Dublin",
|
|
"enabled": true,
|
|
"created_at": "2025-10-01T00:00:00Z",
|
|
"created_by": "did:vm:user:sovereign",
|
|
"next_run": "2025-12-07T06:00:00Z",
|
|
"last_run": "2025-12-06T06:00:00Z",
|
|
"last_status": "completed",
|
|
"run_count": 67,
|
|
"failure_count": 2,
|
|
"constraints": {
|
|
"max_concurrent": 1,
|
|
"skip_if_running": true,
|
|
"maintenance_window_skip": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.4 Triggers
|
|
|
|
**Triggers** define event-driven workflow activation.
|
|
|
|
```json
|
|
{
|
|
"trigger_id": "trig:security-incident",
|
|
"name": "Security Incident Response",
|
|
"workflow_id": "wf:incident-response-initial",
|
|
"trigger_type": "event",
|
|
"event_source": "offsec",
|
|
"event_filter": {
|
|
"type": "offsec_incident",
|
|
"severity": ["critical", "high"]
|
|
},
|
|
"enabled": true,
|
|
"created_at": "2025-11-15T00:00:00Z",
|
|
"created_by": "did:vm:user:sovereign",
|
|
"fire_count": 3,
|
|
"last_fired": "2025-12-06T03:47:00Z",
|
|
"debounce": {
|
|
"enabled": true,
|
|
"window": "5m",
|
|
"group_by": ["incident_id"]
|
|
}
|
|
}
|
|
```
|
|
|
|
**Trigger types**:
|
|
- `event` — fires on VaultMesh events (receipts, alerts, etc.)
|
|
- `webhook` — fires on external HTTP POST
|
|
- `file_watch` — fires on file system changes
|
|
- `mesh_event` — fires on mesh topology changes
|
|
- `approval` — fires when approval is granted/denied
|
|
|
|
### 2.5 Approvals
|
|
|
|
**Approvals** gate workflow continuation on human decisions.
|
|
|
|
```json
|
|
{
|
|
"approval_id": "approval-2025-12-06-001",
|
|
"workflow_id": "wf:production-deploy",
|
|
"execution_id": "exec-2025-12-06-002",
|
|
"step_id": "step-3-deploy",
|
|
"title": "Approve Production Deployment",
|
|
"description": "Deploy Guardian v2.1.0 to production nodes",
|
|
"status": "pending",
|
|
"requested_at": "2025-12-06T10:00:00Z",
|
|
"requested_by": "did:vm:service:ci-pipeline",
|
|
"required_approvers": 2,
|
|
"approvers": ["did:vm:user:sovereign", "did:vm:user:operator-alpha"],
|
|
"current_approvals": [],
|
|
"current_rejections": [],
|
|
"expires_at": "2025-12-06T18:00:00Z",
|
|
"context": {
|
|
"version": "2.1.0",
|
|
"commit": "abc123...",
|
|
"changelog": "https://github.com/vaultmesh/guardian/releases/v2.1.0",
|
|
"test_results": "all passed",
|
|
"affected_nodes": ["brick-01", "brick-02", "brick-03"]
|
|
},
|
|
"notification_channels": ["slack:approvals", "email:approvers"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Mapping to Eternal Pattern
|
|
|
|
### 3.1 Experience Layer (L1)
|
|
|
|
**CLI** (`vm-auto`):
|
|
```bash
|
|
# Workflow management
|
|
vm-auto workflow list
|
|
vm-auto workflow show wf:daily-compliance-check
|
|
vm-auto workflow create --from workflow-def.json
|
|
vm-auto workflow update wf:daily-compliance-check --from workflow-def-v2.json
|
|
vm-auto workflow enable wf:daily-compliance-check
|
|
vm-auto workflow disable wf:daily-compliance-check --reason "maintenance"
|
|
vm-auto workflow delete wf:deprecated-workflow
|
|
|
|
# Manual execution
|
|
vm-auto run wf:daily-compliance-check
|
|
vm-auto run wf:onboarding --input '{"user": "new-operator"}'
|
|
|
|
# Execution monitoring
|
|
vm-auto exec list --workflow wf:daily-compliance-check --last 10
|
|
vm-auto exec show exec-2025-12-06-001
|
|
vm-auto exec logs exec-2025-12-06-001
|
|
vm-auto exec cancel exec-2025-12-06-003 --reason "testing"
|
|
|
|
# Schedules
|
|
vm-auto schedule list
|
|
vm-auto schedule show sched:daily-compliance
|
|
vm-auto schedule pause sched:daily-compliance --until "2025-12-10"
|
|
vm-auto schedule resume sched:daily-compliance
|
|
|
|
# Triggers
|
|
vm-auto trigger list
|
|
vm-auto trigger show trig:security-incident
|
|
vm-auto trigger test trig:security-incident --event test-event.json
|
|
|
|
# Approvals
|
|
vm-auto approval list --status pending
|
|
vm-auto approval show approval-2025-12-06-001
|
|
vm-auto approval approve approval-2025-12-06-001 --comment "Reviewed and approved"
|
|
vm-auto approval reject approval-2025-12-06-001 --reason "Not ready for production"
|
|
|
|
# History
|
|
vm-auto history --workflow wf:daily-compliance-check --from 2025-12-01
|
|
vm-auto history --status failed --last 7d
|
|
```
|
|
|
|
**MCP Tools**:
|
|
- `auto_workflow_list` — list workflows
|
|
- `auto_workflow_run` — execute workflow
|
|
- `auto_execution_status` — get execution status
|
|
- `auto_approval_pending` — list pending approvals
|
|
- `auto_approval_decide` — approve/reject
|
|
- `auto_schedule_next` — next scheduled runs
|
|
|
|
**Portal HTTP**:
|
|
- `GET /auto/workflows` — list workflows
|
|
- `POST /auto/workflows` — create workflow
|
|
- `GET /auto/workflows/{id}` — workflow details
|
|
- `PUT /auto/workflows/{id}` — update workflow
|
|
- `POST /auto/workflows/{id}/run` — execute workflow
|
|
- `GET /auto/executions` — list executions
|
|
- `GET /auto/executions/{id}` — execution details
|
|
- `POST /auto/executions/{id}/cancel` — cancel execution
|
|
- `GET /auto/schedules` — list schedules
|
|
- `GET /auto/triggers` — list triggers
|
|
- `GET /auto/approvals` — list approvals
|
|
- `POST /auto/approvals/{id}/approve` — approve
|
|
- `POST /auto/approvals/{id}/reject` — reject
|
|
|
|
---
|
|
|
|
### 3.2 Engine Layer (L2)
|
|
|
|
#### Step 1 — Plan → `automation_workflow_contract.json`
|
|
|
|
**Workflow Registration Contract**:
|
|
```json
|
|
{
|
|
"operation_id": "auto-op-2025-12-06-001",
|
|
"operation_type": "workflow_register",
|
|
"initiated_by": "did:vm:user:sovereign",
|
|
"initiated_at": "2025-12-06T09:00:00Z",
|
|
"workflow": {
|
|
"id": "wf:treasury-reconciliation",
|
|
"name": "Treasury Reconciliation",
|
|
"version": 1,
|
|
"steps": ["..."],
|
|
"trigger": {
|
|
"type": "schedule",
|
|
"cron": "0 0 * * *"
|
|
}
|
|
},
|
|
"validation": {
|
|
"syntax_valid": true,
|
|
"steps_valid": true,
|
|
"permissions_valid": true
|
|
},
|
|
"requires_approval": false
|
|
}
|
|
```
|
|
|
|
**Execution Contract** (for complex/sensitive workflows):
|
|
```json
|
|
{
|
|
"operation_id": "auto-op-2025-12-06-002",
|
|
"operation_type": "workflow_execute",
|
|
"workflow_id": "wf:production-deploy",
|
|
"workflow_version": 5,
|
|
"triggered_by": "did:vm:service:ci-pipeline",
|
|
"triggered_at": "2025-12-06T10:00:00Z",
|
|
"trigger_type": "webhook",
|
|
"input": {
|
|
"version": "2.1.0",
|
|
"commit": "abc123...",
|
|
"target_nodes": ["brick-01", "brick-02", "brick-03"]
|
|
},
|
|
"requires_approval": true,
|
|
"approval_config": {
|
|
"required_approvers": 2,
|
|
"approver_pool": ["did:vm:user:sovereign", "did:vm:user:operator-alpha", "did:vm:user:operator-bravo"],
|
|
"timeout": "8h"
|
|
},
|
|
"risk_assessment": {
|
|
"impact": "high",
|
|
"reversibility": "medium",
|
|
"affected_services": ["guardian"]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Step 2 — Execute → `automation_execution_state.json`
|
|
|
|
```json
|
|
{
|
|
"execution_id": "exec-2025-12-06-002",
|
|
"workflow_id": "wf:production-deploy",
|
|
"status": "awaiting_approval",
|
|
"created_at": "2025-12-06T10:00:00Z",
|
|
"updated_at": "2025-12-06T10:30:00Z",
|
|
"steps": [
|
|
{
|
|
"step_id": "step-1-build",
|
|
"name": "Build artifacts",
|
|
"status": "completed",
|
|
"started_at": "2025-12-06T10:00:01Z",
|
|
"completed_at": "2025-12-06T10:05:00Z",
|
|
"result": {
|
|
"artifact_hash": "blake3:abc123...",
|
|
"artifact_path": "builds/guardian-2.1.0.tar.gz"
|
|
}
|
|
},
|
|
{
|
|
"step_id": "step-2-test",
|
|
"name": "Run integration tests",
|
|
"status": "completed",
|
|
"started_at": "2025-12-06T10:05:01Z",
|
|
"completed_at": "2025-12-06T10:15:00Z",
|
|
"result": {
|
|
"tests_passed": 147,
|
|
"tests_failed": 0,
|
|
"coverage": 0.89
|
|
}
|
|
},
|
|
{
|
|
"step_id": "step-3-deploy",
|
|
"name": "Deploy to production",
|
|
"status": "awaiting_approval",
|
|
"approval_id": "approval-2025-12-06-001",
|
|
"started_at": "2025-12-06T10:15:01Z"
|
|
},
|
|
{
|
|
"step_id": "step-4-verify",
|
|
"name": "Verify deployment",
|
|
"status": "pending"
|
|
},
|
|
{
|
|
"step_id": "step-5-notify",
|
|
"name": "Notify stakeholders",
|
|
"status": "pending"
|
|
}
|
|
],
|
|
"approval_status": {
|
|
"approval_id": "approval-2025-12-06-001",
|
|
"required": 2,
|
|
"received": 1,
|
|
"approvals": [
|
|
{
|
|
"approver": "did:vm:user:sovereign",
|
|
"decision": "approve",
|
|
"timestamp": "2025-12-06T10:30:00Z",
|
|
"comment": "Tests passed, changelog reviewed"
|
|
}
|
|
]
|
|
},
|
|
"context": {
|
|
"node": "did:vm:node:brick-01",
|
|
"trace_id": "trace-xyz..."
|
|
}
|
|
}
|
|
```
|
|
|
|
**Execution status transitions**:
|
|
```
|
|
pending → running → completed
|
|
↘ failed → (retry) → running
|
|
↘ awaiting_approval → approved → running
|
|
↘ rejected → cancelled
|
|
↘ cancelled
|
|
↘ timed_out
|
|
```
|
|
|
|
#### Step 3 — Seal → Receipts
|
|
|
|
**Workflow Registration Receipt**:
|
|
```json
|
|
{
|
|
"type": "auto_workflow_register",
|
|
"workflow_id": "wf:treasury-reconciliation",
|
|
"workflow_name": "Treasury Reconciliation",
|
|
"version": 1,
|
|
"timestamp": "2025-12-06T09:00:00Z",
|
|
"registered_by": "did:vm:user:sovereign",
|
|
"step_count": 5,
|
|
"trigger_type": "schedule",
|
|
"workflow_hash": "blake3:aaa111...",
|
|
"tags": ["automation", "workflow", "register", "treasury"],
|
|
"root_hash": "blake3:bbb222..."
|
|
}
|
|
```
|
|
|
|
**Workflow Execution Start Receipt**:
|
|
```json
|
|
{
|
|
"type": "auto_workflow_execute",
|
|
"execution_id": "exec-2025-12-06-002",
|
|
"workflow_id": "wf:production-deploy",
|
|
"workflow_version": 5,
|
|
"timestamp": "2025-12-06T10:00:00Z",
|
|
"triggered_by": "did:vm:service:ci-pipeline",
|
|
"trigger_type": "webhook",
|
|
"input_hash": "blake3:ccc333...",
|
|
"node": "did:vm:node:brick-01",
|
|
"tags": ["automation", "execution", "start", "deploy"],
|
|
"root_hash": "blake3:ddd444..."
|
|
}
|
|
```
|
|
|
|
**Workflow Execution Complete Receipt**:
|
|
```json
|
|
{
|
|
"type": "auto_workflow_complete",
|
|
"execution_id": "exec-2025-12-06-002",
|
|
"workflow_id": "wf:production-deploy",
|
|
"workflow_version": 5,
|
|
"timestamp_started": "2025-12-06T10:00:00Z",
|
|
"timestamp_completed": "2025-12-06T11:30:00Z",
|
|
"duration_ms": 5400000,
|
|
"status": "completed",
|
|
"steps_total": 5,
|
|
"steps_completed": 5,
|
|
"steps_failed": 0,
|
|
"output_hash": "blake3:eee555...",
|
|
"approvals_required": 2,
|
|
"approvals_received": 2,
|
|
"tags": ["automation", "execution", "complete", "deploy", "success"],
|
|
"root_hash": "blake3:fff666..."
|
|
}
|
|
```
|
|
|
|
**Schedule Creation Receipt**:
|
|
```json
|
|
{
|
|
"type": "auto_schedule_create",
|
|
"schedule_id": "sched:treasury-reconciliation",
|
|
"workflow_id": "wf:treasury-reconciliation",
|
|
"timestamp": "2025-12-06T09:00:00Z",
|
|
"created_by": "did:vm:user:sovereign",
|
|
"cron": "0 0 * * *",
|
|
"timezone": "UTC",
|
|
"first_run": "2025-12-07T00:00:00Z",
|
|
"tags": ["automation", "schedule", "create"],
|
|
"root_hash": "blake3:ggg777..."
|
|
}
|
|
```
|
|
|
|
**Trigger Fire Receipt**:
|
|
```json
|
|
{
|
|
"type": "auto_trigger_fire",
|
|
"trigger_id": "trig:security-incident",
|
|
"workflow_id": "wf:incident-response-initial",
|
|
"execution_id": "exec-2025-12-06-003",
|
|
"timestamp": "2025-12-06T03:47:00Z",
|
|
"event_type": "offsec_incident",
|
|
"event_id": "INC-2025-12-001",
|
|
"event_severity": "high",
|
|
"debounce_applied": false,
|
|
"tags": ["automation", "trigger", "fire", "incident"],
|
|
"root_hash": "blake3:hhh888..."
|
|
}
|
|
```
|
|
|
|
**Approval Request Receipt**:
|
|
```json
|
|
{
|
|
"type": "auto_approval_request",
|
|
"approval_id": "approval-2025-12-06-001",
|
|
"workflow_id": "wf:production-deploy",
|
|
"execution_id": "exec-2025-12-06-002",
|
|
"step_id": "step-3-deploy",
|
|
"timestamp": "2025-12-06T10:15:01Z",
|
|
"title": "Approve Production Deployment",
|
|
"required_approvers": 2,
|
|
"approver_pool": ["did:vm:user:sovereign", "did:vm:user:operator-alpha", "did:vm:user:operator-bravo"],
|
|
"expires_at": "2025-12-06T18:00:00Z",
|
|
"context_hash": "blake3:iii999...",
|
|
"tags": ["automation", "approval", "request", "deploy"],
|
|
"root_hash": "blake3:jjj000..."
|
|
}
|
|
```
|
|
|
|
**Approval Decision Receipt**:
|
|
```json
|
|
{
|
|
"type": "auto_approval_decision",
|
|
"approval_id": "approval-2025-12-06-001",
|
|
"execution_id": "exec-2025-12-06-002",
|
|
"timestamp": "2025-12-06T10:45:00Z",
|
|
"decision": "approved",
|
|
"approvers": [
|
|
{
|
|
"did": "did:vm:user:sovereign",
|
|
"decision": "approve",
|
|
"timestamp": "2025-12-06T10:30:00Z"
|
|
},
|
|
{
|
|
"did": "did:vm:user:operator-alpha",
|
|
"decision": "approve",
|
|
"timestamp": "2025-12-06T10:45:00Z"
|
|
}
|
|
],
|
|
"quorum_met": true,
|
|
"workflow_resumed": true,
|
|
"tags": ["automation", "approval", "decision", "approved"],
|
|
"root_hash": "blake3:kkk111..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3.3 Ledger Layer (L3)
|
|
|
|
**Receipt Types**:
|
|
|
|
| Type | When Emitted |
|
|
| ------------------------- | ------------------------------- |
|
|
| `auto_workflow_register` | Workflow created/updated |
|
|
| `auto_workflow_execute` | Execution started |
|
|
| `auto_workflow_complete` | Execution completed (any status)|
|
|
| `auto_schedule_create` | Schedule created/modified |
|
|
| `auto_trigger_fire` | Trigger activated |
|
|
| `auto_approval_request` | Approval requested |
|
|
| `auto_approval_decision` | Approval granted/denied |
|
|
|
|
**Merkle Coverage**:
|
|
- All receipts append to `receipts/automation/automation_events.jsonl`
|
|
- `ROOT.automation.txt` updated after each append
|
|
- Guardian anchors Automation root in anchor cycles
|
|
|
|
---
|
|
|
|
## 4. Query Interface
|
|
|
|
`automation_query_events.py`:
|
|
|
|
```bash
|
|
# Workflow history
|
|
vm-auto query --workflow wf:daily-compliance-check
|
|
|
|
# Failed executions
|
|
vm-auto query --type workflow_complete --filter "status == 'failed'"
|
|
|
|
# Approvals by user
|
|
vm-auto query --type approval_decision --filter "approvers[].did == 'did:vm:user:sovereign'"
|
|
|
|
# Trigger fires by event type
|
|
vm-auto query --type trigger_fire --filter "event_type == 'offsec_incident'"
|
|
|
|
# Date range
|
|
vm-auto query --from 2025-12-01 --to 2025-12-06
|
|
|
|
# By workflow category
|
|
vm-auto query --tag compliance
|
|
|
|
# Export for analysis
|
|
vm-auto query --from 2025-01-01 --format csv > automation_2025.csv
|
|
```
|
|
|
|
**Execution Timeline**:
|
|
```bash
|
|
# Show execution timeline with all steps
|
|
vm-auto timeline exec-2025-12-06-002
|
|
|
|
# Output:
|
|
# exec-2025-12-06-002: wf:production-deploy v5
|
|
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
# 10:00:00 ▶ STARTED (triggered by ci-pipeline via webhook)
|
|
# 10:00:01 ├─ step-1-build: STARTED
|
|
# 10:05:00 ├─ step-1-build: COMPLETED (5m) ✓
|
|
# 10:05:01 ├─ step-2-test: STARTED
|
|
# 10:15:00 ├─ step-2-test: COMPLETED (10m) ✓
|
|
# 10:15:01 ├─ step-3-deploy: AWAITING APPROVAL
|
|
# 10:30:00 │ └─ sovereign: APPROVED
|
|
# 10:45:00 │ └─ operator-alpha: APPROVED (quorum met)
|
|
# 10:45:01 ├─ step-3-deploy: STARTED
|
|
# 11:15:00 ├─ step-3-deploy: COMPLETED (30m) ✓
|
|
# 11:15:01 ├─ step-4-verify: STARTED
|
|
# 11:25:00 ├─ step-4-verify: COMPLETED (10m) ✓
|
|
# 11:25:01 ├─ step-5-notify: STARTED
|
|
# 11:30:00 ├─ step-5-notify: COMPLETED (5m) ✓
|
|
# 11:30:00 ■ COMPLETED (1h 30m total)
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Design Gate Checklist
|
|
|
|
| Question | Automation Answer |
|
|
| --------------------- | ---------------------------------------------------------------- |
|
|
| Clear entrypoint? | ✅ CLI (`vm-auto`), MCP tools, Portal HTTP |
|
|
| Contract produced? | ✅ `automation_workflow_contract.json` for registrations/executions |
|
|
| State object? | ✅ `automation_execution_state.json` tracking step progress |
|
|
| Receipts emitted? | ✅ Seven receipt types covering all automation events |
|
|
| Append-only JSONL? | ✅ `receipts/automation/automation_events.jsonl` |
|
|
| Merkle root? | ✅ `ROOT.automation.txt` |
|
|
| Guardian anchor path? | ✅ Automation root included in ProofChain |
|
|
| Query tool? | ✅ `automation_query_events.py` + execution timeline |
|
|
|
|
---
|
|
|
|
## 6. n8n Integration
|
|
|
|
### 6.1 VaultMesh n8n Nodes
|
|
|
|
Custom n8n nodes for VaultMesh integration:
|
|
|
|
```typescript
|
|
// VaultMesh Trigger Node
|
|
{
|
|
name: 'VaultMesh Trigger',
|
|
description: 'Trigger workflow on VaultMesh events',
|
|
inputs: [],
|
|
outputs: ['main'],
|
|
properties: [
|
|
{
|
|
displayName: 'Event Type',
|
|
name: 'eventType',
|
|
type: 'options',
|
|
options: [
|
|
{ name: 'Receipt Emitted', value: 'receipt' },
|
|
{ name: 'Alert Fired', value: 'alert' },
|
|
{ name: 'Anchor Complete', value: 'anchor' },
|
|
{ name: 'Mesh Change', value: 'mesh' }
|
|
]
|
|
},
|
|
{
|
|
displayName: 'Filter',
|
|
name: 'filter',
|
|
type: 'json'
|
|
}
|
|
]
|
|
}
|
|
|
|
// VaultMesh Action Node
|
|
{
|
|
name: 'VaultMesh',
|
|
description: 'Interact with VaultMesh APIs',
|
|
inputs: ['main'],
|
|
outputs: ['main'],
|
|
properties: [
|
|
{
|
|
displayName: 'Operation',
|
|
name: 'operation',
|
|
type: 'options',
|
|
options: [
|
|
{ name: 'Oracle Query', value: 'oracle_query' },
|
|
{ name: 'Emit Receipt', value: 'emit_receipt' },
|
|
{ name: 'Treasury Transfer', value: 'treasury_transfer' },
|
|
{ name: 'Mesh Node Status', value: 'mesh_status' },
|
|
{ name: 'Identity Verify', value: 'identity_verify' }
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 6.2 Workflow-to-Receipt Mapping
|
|
|
|
Every n8n workflow execution produces VaultMesh receipts:
|
|
|
|
```
|
|
n8n Workflow Execution
|
|
│
|
|
▼
|
|
┌─────────────────────────┐
|
|
│ VaultMesh Automation │
|
|
│ Engine Wrapper │
|
|
│ │
|
|
│ • Intercepts start │
|
|
│ • Tracks step progress │
|
|
│ • Captures outputs │
|
|
│ • Handles approvals │
|
|
│ • Emits receipts │
|
|
└─────────────────────────┘
|
|
│
|
|
▼
|
|
JSONL + Merkle
|
|
```
|
|
|
|
### 6.3 n8n Credential Storage
|
|
|
|
VaultMesh credentials for n8n stored securely:
|
|
|
|
```json
|
|
{
|
|
"credential_id": "n8n-cred:vaultmesh-api",
|
|
"type": "vaultmesh_api",
|
|
"name": "VaultMesh Production",
|
|
"data_encrypted": "aes-256-gcm:...",
|
|
"created_at": "2025-12-01T00:00:00Z",
|
|
"created_by": "did:vm:user:sovereign",
|
|
"last_used": "2025-12-06T10:00:00Z",
|
|
"scopes": ["oracle:read", "treasury:read", "automation:execute"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Step Types
|
|
|
|
### 7.1 Built-in Step Types
|
|
|
|
| Step Type | Description | Example Use |
|
|
| --------------- | -------------------------------------------- | -------------------------------- |
|
|
| `mcp_tool` | Call VaultMesh MCP tool | Oracle query, Treasury check |
|
|
| `http_request` | Make HTTP request | External API calls |
|
|
| `condition` | Branch based on expression | Check compliance score |
|
|
| `loop` | Iterate over collection | Process multiple accounts |
|
|
| `parallel` | Execute steps concurrently | Check multiple nodes |
|
|
| `approval` | Wait for human approval | Production deployments |
|
|
| `delay` | Wait for duration | Rate limiting |
|
|
| `notification` | Send notifications | Slack, email, PagerDuty |
|
|
| `script` | Execute custom script | Complex transformations |
|
|
| `sub_workflow` | Call another workflow | Reusable components |
|
|
| `receipt_emit` | Emit custom receipt | Business events |
|
|
|
|
### 7.2 Step Configuration
|
|
|
|
```json
|
|
{
|
|
"step_id": "step-1",
|
|
"name": "Query Treasury Balance",
|
|
"type": "mcp_tool",
|
|
"tool": "treasury_balance",
|
|
"params": {
|
|
"account": "{{ input.account_id }}"
|
|
},
|
|
"timeout": "30s",
|
|
"retry": {
|
|
"max_attempts": 3,
|
|
"backoff": "exponential",
|
|
"initial_delay": "1s"
|
|
},
|
|
"error_handling": {
|
|
"on_error": "continue",
|
|
"fallback_value": {"balance": 0}
|
|
},
|
|
"output_mapping": {
|
|
"balance": "$.result.balance",
|
|
"currency": "$.result.currency"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Integration Points
|
|
|
|
| System | Integration |
|
|
| ---------------- | --------------------------------------------------------------------------- |
|
|
| **Guardian** | Trigger workflows on anchor events; automate anchor scheduling |
|
|
| **Treasury** | Automated reconciliation; scheduled reports; transfer approvals |
|
|
| **Identity** | Credential rotation workflows; onboarding/offboarding automation |
|
|
| **Mesh** | Node provisioning workflows; topology change automation |
|
|
| **OffSec** | Incident response playbooks; automated remediation |
|
|
| **Oracle** | Scheduled compliance checks; gap remediation workflows |
|
|
| **Observability**| Alert-triggered workflows; automated runbook execution |
|
|
|
|
---
|
|
|
|
## 9. Security Model
|
|
|
|
### 9.1 Workflow Permissions
|
|
|
|
```json
|
|
{
|
|
"workflow_id": "wf:production-deploy",
|
|
"permissions": {
|
|
"view": ["did:vm:org:engineering"],
|
|
"execute": ["did:vm:user:sovereign", "did:vm:service:ci-pipeline"],
|
|
"edit": ["did:vm:user:sovereign"],
|
|
"delete": ["did:vm:user:sovereign"],
|
|
"approve": ["did:vm:user:sovereign", "did:vm:user:operator-alpha"]
|
|
},
|
|
"execution_identity": "did:vm:service:automation-engine",
|
|
"secret_access": ["vault:deploy-keys", "vault:api-tokens"]
|
|
}
|
|
```
|
|
|
|
### 9.2 Audit Requirements
|
|
|
|
All workflow operations are receipted for:
|
|
- **Compliance**: Prove workflows executed as designed
|
|
- **Debugging**: Trace execution failures
|
|
- **Accountability**: Track who approved what
|
|
- **Non-repudiation**: Cryptographic proof of execution
|
|
|
|
---
|
|
|
|
## 10. Future Extensions
|
|
|
|
- **Visual workflow builder**: Drag-and-drop in Portal UI
|
|
- **Workflow versioning**: Git-like version control for workflows
|
|
- **A/B testing**: Test workflow variations
|
|
- **Cost tracking**: Treasury integration for workflow execution costs
|
|
- **ML-powered optimization**: Suggest workflow improvements
|
|
- **Cross-mesh orchestration**: Federated workflow execution
|
|
- **Workflow marketplace**: Share/import community workflows
|