# VaultMesh Engine Specifications

## Receipt Types by Scroll

### Drills
| Type | When Emitted |
|------|--------------|
| `security_drill_run` | Drill completed |

### Compliance
| Type | When Emitted |
|------|--------------|
| `oracle_answer` | Compliance question answered |

### Guardian
| Type | When Emitted |
|------|--------------|
| `anchor_success` | Anchor cycle succeeded |
| `anchor_failure` | Anchor cycle failed |
| `anchor_divergence` | Root mismatch detected |

### Treasury
| Type | When Emitted |
|------|--------------|
| `treasury_credit` | Credit entry recorded |
| `treasury_debit` | Debit entry recorded |
| `treasury_settlement` | Multi-party settlement completed |
| `treasury_reconciliation` | Periodic balance verification |

### Mesh
| Type | When Emitted |
|------|--------------|
| `mesh_node_join` | Node registered |
| `mesh_node_leave` | Node deregistered |
| `mesh_route_change` | Route added/removed/modified |
| `mesh_capability_grant` | Capability granted |
| `mesh_capability_revoke` | Capability revoked |
| `mesh_topology_snapshot` | Periodic topology capture |

### OffSec
| Type | When Emitted |
|------|--------------|
| `offsec_incident` | Incident closed |
| `offsec_redteam` | Red team engagement closed |
| `offsec_vuln_discovery` | Vulnerability confirmed |
| `offsec_remediation` | Remediation verified |
| `offsec_threat_intel` | New IOC/TTP added |
| `offsec_forensic_snapshot` | Forensic capture taken |

### Identity
| Type | When Emitted |
|------|--------------|
| `identity_did_create` | New DID registered |
| `identity_did_rotate` | Key rotation completed |
| `identity_credential_issue` | Credential issued |
| `identity_credential_revoke` | Credential revoked |
| `identity_auth_event` | Authentication attempt |
| `identity_capability_grant` | Capability granted |
| `identity_capability_exercise` | Capability used |

### Observability
| Type | When Emitted |
|------|--------------|
| `obs_metric_anomaly` | Anomaly detected/resolved |
| `obs_log_alert` | Log-based alert triggered |
| `obs_trace_summary` | Critical operation traced |
| `obs_health_snapshot` | Daily health capture |
| `obs_slo_breach` | SLO target missed |
| `obs_capacity_event` | Resource threshold crossed |

### Automation
| Type | When Emitted |
|------|--------------|
| `auto_workflow_run` | Workflow execution completed |
| `auto_scheduled_task` | Scheduled task executed |
| `auto_agent_action` | Agent took action |
| `auto_trigger_event` | External trigger received |
| `auto_approval_gate` | Approval gate resolved |
| `auto_error_recovery` | Error recovery completed |

### PsiField
| Type | When Emitted |
|------|--------------|
| `psi_phase_transition` | Phase change |
| `psi_emergence_event` | Emergent behavior detected |
| `psi_transmutation` | Negative → capability transform |
| `psi_resonance` | Cross-system synchronization |
| `psi_integration` | Learning crystallized |
| `psi_oracle_insight` | Significant Oracle insight |

### Federation
| Type | When Emitted |
|------|--------------|
| `fed_trust_proposal` | Trust proposal submitted |
| `fed_trust_established` | Federation agreement active |
| `fed_trust_revoked` | Federation terminated |
| `fed_witness_event` | Remote root witnessed |
| `fed_cross_anchor` | Remote root included in anchor |
| `fed_schema_sync` | Schema versions synchronized |

### Governance
| Type | When Emitted |
|------|--------------|
| `gov_proposal` | Proposal submitted |
| `gov_vote` | Vote cast |
| `gov_ratification` | Proposal ratified |
| `gov_amendment` | Constitution amended |
| `gov_executive_order` | Executive order issued |
| `gov_violation` | Violation detected |
| `gov_enforcement` | Enforcement action taken |

---

## Engine Contract Templates

### Treasury Settlement Contract
```json
{
  "settlement_id": "settle-YYYY-MM-DD-NNN",
  "title": "Settlement Title",
  "initiated_by": "did:vm:node:portal-01",
  "initiated_at": "ISO8601",
  "parties": ["did:vm:node:...", "did:vm:node:..."],
  "entries": [
    {
      "entry_id": "entry-NNN",
      "type": "debit|credit",
      "account": "acct:vm:node:...:type",
      "amount": 0.00,
      "currency": "EUR",
      "memo": "Description"
    }
  ],
  "requires_signatures": ["node-id", "node-id"],
  "settlement_type": "inter_node_resource|vendor_payment|..."
}
```

### Mesh Change Contract
```json
{
  "change_id": "mesh-change-YYYY-MM-DD-NNN",
  "title": "Change Title",
  "initiated_by": "did:vm:node:portal-01",
  "initiated_at": "ISO8601",
  "change_type": "node_expansion|route_update|...",
  "operations": [
    {
      "op_id": "op-NNN",
      "operation": "node_join|route_add|capability_grant|...",
      "target": "did:vm:node:...",
      "config": {}
    }
  ],
  "requires_approval": ["node-id"],
  "rollback_on_failure": true
}
```

### OffSec Incident Contract
```json
{
  "case_id": "INC-YYYY-MM-NNN",
  "case_type": "incident",
  "title": "Incident Title",
  "severity": "critical|high|medium|low",
  "created_at": "ISO8601",
  "phases": [
    {
      "phase_id": "phase-N-name",
      "name": "Triage|Containment|Eradication|Recovery",
      "objectives": ["..."],
      "checklist": ["..."]
    }
  ],
  "assigned_responders": ["did:vm:human:..."],
  "escalation_path": ["..."]
}
```

### Identity Operation Contract
```json
{
  "operation_id": "idop-YYYY-MM-DD-NNN",
  "operation_type": "key_rotation_ceremony|...",
  "title": "Operation Title",
  "initiated_by": "did:vm:human:...",
  "initiated_at": "ISO8601",
  "target_did": "did:vm:node:...",
  "steps": [
    {
      "step_id": "step-N-name",
      "action": "action_name",
      "params": {}
    }
  ],
  "rollback_on_failure": true
}
```

### Transmutation Contract
```json
{
  "transmutation_id": "psi-transmute-YYYY-MM-DD-NNN",
  "title": "Transmutation Title",
  "initiated_by": "did:vm:human:...",
  "initiated_at": "ISO8601",
  "input_material": {
    "type": "security_incident|vulnerability|...",
    "reference": "INC-YYYY-MM-NNN"
  },
  "target_phase": "citrinitas",
  "transmutation_steps": [
    {
      "step_id": "step-N-name",
      "name": "Step Name",
      "action": "action_name",
      "expected_output": "output_path"
    }
  ],
  "witnesses_required": ["node-id", "node-id"],
  "success_criteria": {}
}
```

---

## State Machine Transitions

### Settlement Status
```
draft → pending_signatures → executing → completed
                          ↘ disputed → resolved → completed
                          ↘ expired
```

### Incident Status
```
reported → triaging → investigating → contained → eradicating → recovered → closed
                   ↘ false_positive → closed
```

### Mesh Change Status
```
draft → pending_approval → in_progress → completed
                                       ↘ partial_failure → rollback → rolled_back
                                       ↘ failed → rollback → rolled_back
```

### Alchemical Phase
```
nigredo → albedo → citrinitas → rubedo
    ↑                              │
    └──────────────────────────────┘
         (cycle continues)
```

---

## Capability Types

| Capability | Description | Typical Holders |
|------------|-------------|-----------------|
| `anchor` | Submit roots to anchor backends | Guardian nodes |
| `storage` | Store receipts and artifacts | Infrastructure nodes |
| `compute` | Execute drills, run agents | BRICK nodes |
| `oracle` | Issue compliance answers | Oracle nodes |
| `admin` | Grant/revoke capabilities | Portal, Sovereign |
| `federate` | Establish cross-mesh trust | Portal |

---

## Trust Levels (Federation)

| Level | Name | Description |
|-------|------|-------------|
| 0 | `isolated` | No federation |
| 1 | `observe` | Read-only witness |
| 2 | `verify` | Mutual verification |
| 3 | `attest` | Cross-attestation |
| 4 | `integrate` | Shared scrolls |

---

## Account Types (Treasury)

| Type | Purpose |
|------|---------|
| `operational` | Day-to-day infrastructure spend |
| `reserve` | Long-term holdings, runway |
| `escrow` | Held pending settlement |
| `external` | Counterparty accounts |

---

## Node Types (Mesh)

| Type | Purpose |
|------|---------|
| `infrastructure` | BRICK servers, compute |
| `edge` | Mobile devices, field endpoints |
| `oracle` | Compliance oracle instances |
| `guardian` | Dedicated anchor/sentinel |
| `external` | Federated nodes |

---

## Severity Levels

| Level | Description |
|-------|-------------|
| `critical` | Active breach, data exfiltration |
| `high` | Confirmed attack, potential breach |
| `medium` | Suspicious activity, policy violation |
| `low` | Anomaly, informational |