Initialize repository snapshot

2025-12-27 00:10:32 +00:00
commit 110d644e10
281 changed files with 40331 additions and 0 deletions
--- a/docs/VAULTMESH-AUTOMATION-ENGINE.md
+++ b/docs/VAULTMESH-AUTOMATION-ENGINE.md
@@ -0,0 +1,907 @@
+# 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