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

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:

test_vmhash_blake3_deterministic — same input = same hash
test_vmhash_from_json — JSON serialization hashes correctly
test_merkle_root_empty — empty list returns blake3("empty")
test_merkle_root_single — single hash returns itself
test_merkle_root_pair — two hashes combine correctly
test_merkle_root_odd — odd number duplicates last
test_did_new — creates valid did:vm:type:name
test_did_parse_valid — parses did:vm:... correctly
test_did_parse_invalid — rejects non-vm DIDs
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

//! 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:

test_compute_scroll_root_empty — missing file returns empty hash
test_compute_scroll_root_single_line — single entry returns its hash
test_compute_scroll_root_multiple — computes correct merkle root
test_anchor_creates_receipt — anchor_all writes to JSONL
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

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

Implementation Order

Now: Create .gitlab-ci.yml + add 10 tests to vaultmesh-core
Today: Implement GuardianEngine with 5 tests
Tomorrow: TreasuryEngine basics
This week: Remaining engines (parallelize)
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

6.0 KiB Raw Permalink Blame History