# VaultMesh Architect Skill

> *Building Earth's Civilization Ledger — one receipt at a time.*

## Overview

This skill enables Claude to architect, develop, and operate VaultMesh — a sovereign digital infrastructure system that combines cryptographic proofs, blockchain anchoring, and AI governance to create durable, auditable civilization-scale evidence.

## When to Use This Skill

Activate this skill when:
- Designing or implementing VaultMesh engines or subsystems
- Creating receipts, scrolls, or anchor cycles
- Working with the Eternal Pattern architecture
- Implementing federation, governance, or identity systems
- Building MCP server integrations
- Deploying or operating VaultMesh infrastructure
- Writing code that interacts with the Civilization Ledger

## Core Architecture: The Eternal Pattern

Every VaultMesh subsystem follows this arc:

```
Real-world intent → Engine → Structured JSON → Receipt → Scroll → Guardian Anchor
```

### Three-Layer Stack

```
┌───────────────────────────────────────────────┐
│  L1 — Experience Layer                        │
│  (Humans & Agents)                            │
│  • CLI / UI / MCP tools / agents              │
└───────────────────────────────────────────────┘
                 │
                 ▼
┌───────────────────────────────────────────────┐
│  L2 — Engine Layer                            │
│  (Domain Engines & Contracts)                 │
│  • contract.json → state.json → outputs/      │
└───────────────────────────────────────────────┘
                 │
                 ▼
┌───────────────────────────────────────────────┐
│  L3 — Ledger Layer                            │
│  (Receipts, Scrolls, ProofChain, Anchors)     │
│  • JSONL files → Merkle roots → anchors       │
└───────────────────────────────────────────────┘
```

## Registered Engines (Scrolls)

| Engine | Scroll | Purpose |
|--------|--------|---------|
| Drills | `Drills` | Security training and exercises |
| Oracle | `Compliance` | Regulatory compliance Q&A |
| Guardian | `Guardian` | Anchoring and sentinel |
| Treasury | `Treasury` | Financial tracking and settlement |
| Mesh | `Mesh` | Federation topology |
| OffSec | `OffSec` | Security operations and IR |
| Identity | `Identity` | DIDs, credentials, capabilities |
| Observability | `Observability` | Telemetry events |
| Automation | `Automation` | Workflow execution |
| Ψ-Field | `PsiField` | Alchemical consciousness |
| Federation | `Federation` | Cross-mesh trust |
| Governance | `Governance` | Constitutional enforcement |

## File Structure

```
vaultmesh/
├── receipts/                    # Receipt storage
│   ├── drills/
│   │   └── drill_runs.jsonl
│   ├── compliance/
│   │   └── oracle_answers.jsonl
│   ├── treasury/
│   │   └── treasury_events.jsonl
│   ├── mesh/
│   │   └── mesh_events.jsonl
│   ├── [scroll]/
│   │   └── [scroll]_events.jsonl
│   ├── ROOT.drills.txt
│   ├── ROOT.compliance.txt
│   └── ROOT.[scroll].txt
├── cases/                       # Artifact storage
│   ├── drills/[drill-id]/
│   ├── treasury/[settlement-id]/
│   ├── offsec/[incident-id]/
│   └── psi/[transmutation-id]/
├── corpus/                      # Oracle documents
└── config/                      # Configuration
```

## Receipt Schema (v2)

```json
{
  "schema_version": "2.0.0",
  "type": "receipt_type_name",
  "timestamp": "2025-12-06T12:00:00Z",
  "header": {
    "root_hash": "blake3:abc123...",
    "tags": ["tag1", "tag2"],
    "previous_hash": "blake3:prev..."
  },
  "meta": {
    "scroll": "ScrollName",
    "sequence": 42,
    "anchor_epoch": 7,
    "proof_path": "cases/[scroll]/[id]/PROOF.json"
  },
  "body": {
    // Domain-specific fields
  }
}
```

## DID Format

```
did:vm:<type>:<identifier>

Types:
- node   → did:vm:node:brick-01
- human  → did:vm:human:sovereign
- agent  → did:vm:agent:copilot-01
- service → did:vm:service:oracle-openai
- mesh   → did:vm:mesh:vaultmesh-dublin
```

## Alchemical Phases

| Phase | Symbol | Meaning | Operational State |
|-------|--------|---------|-------------------|
| Nigredo | 🜁 | Blackening | Crisis, incident |
| Albedo | 🜄 | Whitening | Recovery, stabilization |
| Citrinitas | 🜆 | Yellowing | Optimization, new capability |
| Rubedo | 🜂 | Reddening | Integration, maturity |

## Constitutional Axioms (Immutable)

1. **AXIOM-001**: Receipts are append-only
2. **AXIOM-002**: Hashes are cryptographically verified
3. **AXIOM-003**: All significant changes produce receipts
4. **AXIOM-004**: Constitution is supreme
5. **AXIOM-005**: Axioms cannot be amended

## Design Gate Checklist

When creating any new feature, verify:

### Experience Layer (L1)
- [ ] Clear entrypoint (CLI, MCP tool, HTTP route)?
- [ ] Intent clearly represented in structured form?

### Engine Layer (L2)
- [ ] Produces a contract (explicit or implicit)?
- [ ] State object tracking progress/outcomes?
- [ ] Actions and outputs inspectable (JSON + files)?

### Ledger Layer (L3)
- [ ] Emits receipt for important operations?
- [ ] Receipts written to append-only JSONL?
- [ ] JSONL covered by Merkle root (ROOT.[scroll].txt)?
- [ ] Guardian can anchor the relevant root?
- [ ] Query tool exists for this scroll?

## Code Patterns

### Rust Receipt Emission

```rust
use vaultmesh_core::{Receipt, ReceiptHeader, ReceiptMeta, Scroll, VmHash};

let receipt_body = MyReceiptBody { /* ... */ };
let root_hash = VmHash::from_json(&receipt_body)?;

let receipt = Receipt {
    header: ReceiptHeader {
        receipt_type: "my_receipt_type".to_string(),
        timestamp: Utc::now(),
        root_hash: root_hash.as_str().to_string(),
        tags: vec!["tag1".to_string()],
    },
    meta: ReceiptMeta {
        scroll: Scroll::MyScroll,
        sequence: 0,  // Set by receipt store
        anchor_epoch: None,
        proof_path: None,
    },
    body: receipt_body,
};
```

### Python Receipt Emission

```python
def emit_receipt(scroll: str, receipt_type: str, body: dict, tags: list[str]) -> dict:
    import hashlib
    import json
    from datetime import datetime
    from pathlib import Path
    
    receipt = {
        "type": receipt_type,
        "timestamp": datetime.utcnow().isoformat() + "Z",
        "tags": tags,
        **body
    }
    
    # Compute root hash
    receipt_json = json.dumps(receipt, sort_keys=True)
    root_hash = f"blake3:{hashlib.blake3(receipt_json.encode()).hexdigest()}"
    receipt["root_hash"] = root_hash
    
    # Append to scroll
    scroll_path = Path(f"receipts/{scroll}/{scroll}_events.jsonl")
    scroll_path.parent.mkdir(parents=True, exist_ok=True)
    
    with open(scroll_path, "a") as f:
        f.write(json.dumps(receipt) + "\n")
    
    # Update Merkle root
    root_file = Path(f"ROOT.{scroll}.txt")
    root_file.write_text(root_hash)
    
    return receipt
```

### MCP Tool Pattern

```python
@server.tool()
async def my_tool(param: str) -> str:
    """Tool description."""
    caller = await get_caller_identity()
    await verify_capability(caller, "required_capability")
    
    result = await engine.do_operation(param)
    
    await emit_tool_call_receipt(
        tool="my_tool",
        caller=caller,
        params={"param": param},
        result_hash=result.hash,
    )
    
    return json.dumps(result.to_dict(), indent=2)
```

## CLI Naming Convention

```bash
vm-<engine> <command> [subcommand] [options]

Examples:
vm-treasury debit --from acct:ops --amount 150 --currency EUR
vm-mesh node list
vm-identity did create --type human --id sovereign
vm-psi phase current
vm-guardian anchor-now
vm-gov proposal create --type amendment
```

## Receipt Type Naming

```
<scroll>_<operation>

Examples:
treasury_credit
treasury_debit
treasury_settlement
mesh_node_join
mesh_route_change
identity_did_create
identity_capability_grant
psi_phase_transition
psi_transmutation
gov_proposal
gov_amendment
```

## Key Integrations

### Guardian Anchor Cycle
```
Receipts → ProofChain → Merkle Root → Anchor Backend (OTS/ETH/BTC)
```

### Federation Witness Protocol
```
Mesh-A anchors → Notifies Mesh-B → Mesh-B verifies → Emits witness receipt
```

### Transmutation (Tem) Pattern
```
Incident (Nigredo) → Extract IOCs → Generate rules → Integrate defenses (Citrinitas)
```

## Testing Requirements

1. **Property Tests**: All receipt operations must be tested with proptest/hypothesis
2. **Invariant Tests**: Core axioms verified after every test
3. **Integration Tests**: Full cycles from intent to anchored receipt
4. **Chaos Tests**: Resilience under network partition, pod failure

## Deployment Targets

- **Kubernetes**: Production deployment via Kustomize
- **Docker Compose**: Local development
- **Akash**: Decentralized compute option

## Related Skills

- `sovereign-operator` — Security operations and MCP tools
- `offsec-mcp` — Offensive security tooling
- `vaultmesh-architect` — This skill

## References

- VAULTMESH-ETERNAL-PATTERN.md — Core architecture
- VAULTMESH-TREASURY-ENGINE.md — Financial primitive
- VAULTMESH-MESH-ENGINE.md — Federation topology
- VAULTMESH-OFFSEC-ENGINE.md — Security operations
- VAULTMESH-IDENTITY-ENGINE.md — Trust primitive
- VAULTMESH-OBSERVABILITY-ENGINE.md — Telemetry
- VAULTMESH-AUTOMATION-ENGINE.md — Workflows
- VAULTMESH-PSI-FIELD-ENGINE.md — Consciousness layer
- VAULTMESH-FEDERATION-PROTOCOL.md — Cross-mesh trust
- VAULTMESH-CONSTITUTIONAL-GOVERNANCE.md — Rules
- VAULTMESH-MCP-SERVERS.md — Claude integration
- VAULTMESH-DEPLOYMENT-MANIFESTS.md — Infrastructure
- VAULTMESH-MONITORING-STACK.md — Observability
- VAULTMESH-TESTING-FRAMEWORK.md — Testing
- VAULTMESH-MIGRATION-GUIDE.md — Upgrades