# 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