339 lines
10 KiB
Markdown
339 lines
10 KiB
Markdown
# 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
|