vm-cloud/UPGRADE_PATH.md

vm-cloud Upgrade Path (VaultMesh)

This repo is designed to evolve into a verifiable operator subsystem: actions → receipts → ledger → merkle → anchors.

Current state (this artifact)

• Per-server lock files (~/.cache/vm-cloud/locks/<serverId>.lock) with --force
• Receipts written to outputs/receipts/ with:
  • canonical hashing (blake3 + sha256)
  • prev_blake3 chaining
  • HEAD.json updated on every receipt
• Plan/apply boundary:
  • --dry-run emits a plan to outputs/plans/
  • vmc apply --plan ... executes and links the plan hashes into the receipt
• Operator signing (Ed25519):
  • vmc keygen
  • vmc sign receipt <receipt>
  • vmc verify receipt <receipt> --sig
  • vmc verify chain --sig
• Merkle commitment:
  • vmc merkle receipts writes outputs/ledger/merkle-*.json

Next steps (recommended)

1) CI gate: “ledger must verify”

In CI, after tests:

npm run build
node dist/cli.js verify chain --head

Optionally require signatures:

node dist/cli.js verify chain --sig --head

2) Anchoring the Merkle root

The merkle root file is your commitment point. Anchor it using your preferred substrate:

• btc-anchor: commit root into an OP_RETURN / inscription scheme (policy-dependent)
• eth-anchor: store root in a contract/event log
• rfc3161-anchor: timestamp the root using an RFC3161 TSA

The anchoring step should store:

• root
• created_at
• leaf_count
• head_blake3
• a signature over the above (operator key)

3) Multi-operator keys + rotation

• Add a key_id (KID) and embed it in receipts
• Allow multiple trusted public keys for verification
• Add vmc keys list and vmc keys trust <pub> for distributed ops

4) MCP plan/apply flow

Expose “plan” and “apply” as MCP tools so an agent can:

• generate a plan (dry-run)
• have a human approve/sign the plan
• apply it and produce a linked receipt

5) Drift + policy checks

• Add vmc policy check that evaluates server labels, naming, and network posture
• Make policy checks emit signed attestations into the same ledger