Initialize repository snapshot

PLAN.md

@@ -0,0 +1,215 @@
+# 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