vm-core/PLAN.md

# VaultMesh Implementation Plan
**Based on Level-of-Done Assessment (2.5/5 → Target 4/5)**

---

## Phase 1: Foundation (Today)

### 1.1 Add GitLab CI Pipeline
**File:** `.gitlab-ci.yml`

```yaml
stages:
  - build
  - test
  - lint

rust-build:
  stage: build
  image: rust:1.75
  script:
    - cargo build --workspace --locked
  cache:
    key: cargo-$CI_COMMIT_REF_SLUG
    paths:
      - target/
      - ~/.cargo/registry/

rust-test:
  stage: test
  image: rust:1.75
  script:
    - cargo test --workspace --locked
  cache:
    key: cargo-$CI_COMMIT_REF_SLUG
    paths:
      - target/

rust-lint:
  stage: lint
  image: rust:1.75
  script:
    - rustup component add clippy rustfmt
    - cargo fmt --check
    - cargo clippy --workspace -- -D warnings
  allow_failure: true
```

**Acceptance:** Pipeline runs on push, blocks MR on test failure.

---

### 1.2 Add Unit Tests to vaultmesh-core

**File:** `vaultmesh-core/src/lib.rs` — add test module

Tests to add:
1. `test_vmhash_blake3_deterministic` — same input = same hash
2. `test_vmhash_from_json` — JSON serialization hashes correctly
3. `test_merkle_root_empty` — empty list returns blake3("empty")
4. `test_merkle_root_single` — single hash returns itself
5. `test_merkle_root_pair` — two hashes combine correctly
6. `test_merkle_root_odd` — odd number duplicates last
7. `test_did_new` — creates valid did:vm:type:name
8. `test_did_parse_valid` — parses did:vm:... correctly
9. `test_did_parse_invalid` — rejects non-vm DIDs
10. `test_receipt_serialization` — Receipt round-trips through JSON

**Acceptance:** `cargo test -p vaultmesh-core` shows 10 passing tests.

---

## Phase 2: Guardian Engine (This Week)

### 2.1 Implement Guardian Engine in Rust

**File:** `vaultmesh-guardian/src/lib.rs`

```rust
//! VaultMesh Guardian Engine - Merkle root anchoring

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use std::path::Path;
use vaultmesh_core::{Receipt, ReceiptHeader, ReceiptMeta, Scroll, VmHash, merkle_root};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AnchorReceipt {
    pub anchor_id: String,
    pub anchor_epoch: u64,
    pub anchor_by: String,
    pub backend: String,
    pub roots: std::collections::HashMap<String, String>,
    pub scrolls: Vec<String>,
    pub anchor_hash: String,
}

pub struct GuardianEngine {
    pub receipts_root: std::path::PathBuf,
    pub guardian_did: String,
}

impl GuardianEngine {
    pub fn new(receipts_root: impl AsRef<Path>, guardian_did: &str) -> Self {
        Self {
            receipts_root: receipts_root.as_ref().to_path_buf(),
            guardian_did: guardian_did.to_string(),
        }
    }

    /// Compute Merkle root for a scroll's JSONL file
    pub fn compute_scroll_root(&self, scroll: Scroll) -> std::io::Result<VmHash> {
        let path = self.receipts_root.join(scroll.jsonl_path());
        if !path.exists() {
            return Ok(VmHash::blake3(b"empty"));
        }
        // Read lines, hash each, compute merkle root
        let content = std::fs::read_to_string(&path)?;
        let hashes: Vec<VmHash> = content
            .lines()
            .filter(|l| !l.trim().is_empty())
            .map(|l| VmHash::blake3(l.as_bytes()))
            .collect();
        Ok(merkle_root(&hashes))
    }

    /// Anchor all scrolls and emit guardian receipt
    pub fn anchor_all(&self, scrolls: &[Scroll]) -> std::io::Result<Receipt<AnchorReceipt>> {
        // Implementation: compute roots, build receipt, append to JSONL
        todo!("Implement anchor_all")
    }
}
```

**Tests to add:**
1. `test_compute_scroll_root_empty` — missing file returns empty hash
2. `test_compute_scroll_root_single_line` — single entry returns its hash
3. `test_compute_scroll_root_multiple` — computes correct merkle root
4. `test_anchor_creates_receipt` — anchor_all writes to JSONL
5. `test_anchor_hash_deterministic` — same inputs = same anchor_hash

**Acceptance:** `cargo test -p vaultmesh-guardian` shows 5+ passing tests.

---

## Phase 3: Treasury Engine (Next Week)

### 3.1 Implement Treasury Basics

**Structures:**
- `Budget { id, name, allocated, spent, currency }`
- `BudgetCreateReceipt`
- `BudgetSpendReceipt`
- `TreasuryEngine { budgets: HashMap }`

**Methods:**
- `create_budget()` → emits receipt
- `record_spend()` → emits receipt
- `get_balance()` → returns remaining

**Tests:** 5 unit tests covering create/spend/balance flows.

---

## Phase 4: Remaining Engines (Weeks 2-3)

| Engine | Core Implementation | Tests |
|--------|---------------------|-------|
| vaultmesh-mesh | Node registry, sync receipts | 5 tests |
| vaultmesh-observability | Metrics exporter, health receipts | 5 tests |
| vaultmesh-offsec | Incident/vuln receipt emission | 5 tests |
| vaultmesh-psi | PSI field primitives | 5 tests |
| vaultmesh-automation | Skill validation receipts | 5 tests |

---

## Phase 5: Python Parity & Docs

1. Add `requirements.txt` with test deps (pytest, blake3, click, pynacl)
2. Add pytest tests for CLI flows
3. Update README with quickstart
4. Add `CONTRIBUTING.md` with PR checklist

---

## Implementation Order

1. **Now:** Create `.gitlab-ci.yml` + add 10 tests to vaultmesh-core
2. **Today:** Implement GuardianEngine with 5 tests
3. **Tomorrow:** TreasuryEngine basics
4. **This week:** Remaining engines (parallelize)
5. **Next week:** Python tests + docs polish

---

## Files to Create/Modify

| Action | File | Description |
|--------|------|-------------|
| CREATE | `.gitlab-ci.yml` | CI pipeline |
| MODIFY | `vaultmesh-core/src/lib.rs` | Add test module |
| MODIFY | `vaultmesh-core/src/hash.rs` | Add tests |
| MODIFY | `vaultmesh-core/src/did.rs` | Add tests |
| MODIFY | `vaultmesh-guardian/src/lib.rs` | Full implementation |
| MODIFY | `vaultmesh-guardian/Cargo.toml` | Add deps |
| MODIFY | `vaultmesh-treasury/src/lib.rs` | Full implementation |
| CREATE | `requirements.txt` | Python deps for CI |

---

## Success Criteria

- [ ] CI pipeline runs on every push
- [ ] `cargo test --workspace` shows 30+ tests passing
- [ ] All engines emit receipts (not just stubs)
- [ ] Level-of-Done score reaches 4/5