vm-core/spec/BLUEPRINT_SPEC.md

VaultMesh Blueprint Spec (v0)

This document defines the concrete, auditable objects and invariants implied by the VaultMesh Blueprint. It is written to be implementable and reviewable by engineers and auditors.

Scope

This spec covers:

• Local-first evidence storage (SQLite ledger)
• File-based receipt scrolls and Merkle roots
• Sealing (deterministic digests over a set of events) and external anchoring
• ShadowReceipts (“proof of restraint”) as a first-class, queryable record
• Evolution control (epochs) and bounded automation (Autogene: read-only)

Core Objects

1) ProofRune

A generic “proof container” for any payload that must be replayable, hashable, and auditable.

Minimal shape:

{
  "payload": { "any": "json" },
  "capability_hash": "hex",
  "merkle_root": "hex|0",
  "epoch": "nigredo|albedo|rubedo",
  "ts": "ISO-8601 Z"
}

Storage:

• As an on-disk file referenced by a row in proof_artifacts (preferred), or
• As a JSON object in proof_artifacts.meta_json for small payloads.

2) OuroborosReceipt (Seal Bundle + External Anchor)

An OuroborosReceipt is a sealed summary proof for a selected set of events, anchored externally.

It has two layers:

1. Local seal bundle (SQLite witness): a deterministic digest over a chosen set.
2. External anchor (pipeline witness): an immutable timestamp/anchor referencing the seal digest.

Minimal fields (local seal bundle file):

{
  "format": "vm-ouroboros-seal-v0",
  "schema_version": 3,
  "schema_last_migration": "0003_shadow_receipts.sql",
  "seal_id": "uuid",
  "sealed_at": "ISO-8601 Z",
  "digest_algo": "sha256",
  "selection": {
    "scope": "time_window|trace_set",
    "since": "ISO-8601 Z|null",
    "until": "ISO-8601 Z|null",
    "trace_ids": ["uuid", "..."],
    "kinds": ["tool_invocations", "mcp_calls", "proof_artifacts"]
  },
  "digest": {
    "algorithm": "sha256",
    "hex": "..."
  },
  "bounds": {
    "min_ts": "ISO-8601 Z|null",
    "max_ts": "ISO-8601 Z|null"
  },
  "inputs": {
    "sqlite_db_path": "path",
    "receipt_roots": ["receipts/**/ROOT.*.txt"]
  }
}

External anchor evidence is recorded as an additional proof_artifacts row that either:

• embeds the anchor payload (e.g., RFC-3161 token, txid), or
• references an artifact path containing it.

3) ShadowReceipt (Proof of Restraint)

A ShadowReceipt records a counterfactual/near-miss/aborted path without rewriting canonical history.

Minimal row fields (table shadow_receipts):

• id: uuid
• ts: ISO-8601 Z
• horizon_id: stable identifier for a decision horizon
• counterfactual_hash: hash of a canonicalized counterfactual description
• entropy_delta: numeric drift/uncertainty signal (policy-defined meaning)
• reason: short reason the path was not executed
• observer_signature: signature/attestation of the observer (human or system identity)
• trace_id: correlation id linking to tool/MCP/receipt chain
• meta_json: optional redacted metadata

ShadowReceipts are not part of the per-engine Merkle roots by default; they remain queryable and auditable via SQLite + seals.

4) Guardians

Guardians are bounded subsystems that:

• ingest signals (telemetry, anomalies, drift indicators)
• produce evidence (receipts/artifacts)
• produce proposals (never unilateral law rewrites)

In implementation terms, a Guardian is a module that consumes ledger/scroll state and emits:

• proof_artifacts (reports, policies, recommended changes)
• (optionally) receipt scroll entries in its engine domain
• (optionally) ShadowReceipts

5) Directed Evolution Engine (DEE)

DEE is a controller that converts signals into proposed system changes.

Outputs are always proposals, not direct execution. Executing a proposal requires:

• capability authorization, and
• an auditable receipt trail (scroll + seal).

DEE outputs are stored as proof_artifacts with stable formats (e.g., vm-dee-proposal-v0).

6) Epoch

epoch is an explicit system mode included in ProofRunes and proposals:

• nigredo: maximum learning; conservative execution
• albedo: normalization and stabilization
• rubedo: directed transformation (strict gating)

Epoch changes are themselves auditable events (receipt + seal).

7) Autogene (Read-only)

Autogene is a bounded anticipatory system:

• It can analyze and forecast.
• It cannot execute changes directly.

Autogene outputs are stored as proof_artifacts (e.g., autogene_forecast, autogene_recommendation) and require the same approval/execution gates as any other proposal.

Invariants (Must Hold)

1. Local-first evidence: every externally anchored claim must correspond to a locally stored seal bundle (SQLite witness).
2. Deterministic sealing: the seal digest is deterministic for a given selection + canonicalization rules.
3. Append-only evidence: evidence is never rewritten in place; corrections are new receipts/artifacts referencing prior ids/hashes.
4. Action gating: proposals never execute themselves; execution requires capability + receipt trail.
5. Autogene read-only: Autogene cannot mutate state; it only emits artifacts.
6. Shadow separation: ShadowReceipts do not retroactively alter canonical history; they are additive evidence.
7. Trace continuity: a trace_id links the full chain across:
   • tool_invocations.trace_id
   • mcp_calls.trace_id
   • proof_artifacts.trace_id
   • shadow_receipts.trace_id (planned)
8. Redaction for storage: stored payloads must be redacted/hashed where appropriate (secrets never stored in plaintext).

Evidence Artifacts (What Proves What)

SQLite ledger (queryable witness)

Current tables:

• tool_invocations: “what local tools did” with redacted inputs/outputs.
• mcp_calls: “what boundary calls happened” with redacted request/response.
• proof_artifacts: “what proof objects exist” (files and/or meta) with content hashes.
• shadow_receipts: “what paths were considered and not executed” (proof of restraint).

Receipt scrolls + roots (tamper-evident chronology)

Per-engine JSONL scrolls and their Merkle roots (e.g., console engine):

• receipts/**/ENGINE_EVENTS.jsonl
• receipts/**/ROOT.*.txt

These are inputs into sealing and external anchoring, but they remain independently verifiable.

Seals and anchors (bridge to external immutability)

• Seal bundle file: stored as proof_artifacts with a strong digest.
• External anchor evidence: stored as a second proof_artifacts row referencing or embedding:
  • RFC-3161 timestamp token
  • release-time Merkle root(s)
  • blockchain txid(s) or other anchoring proof

Failure Modes (Detection + Response)

1. Ledger tampering / local rollback

   • Detect: mismatch between proof_artifacts.sha256_hex and file contents; seal digest mismatch; missing expected rows.
   • Respond: emit a new artifact documenting divergence; re-seal; escalate to external anchor verification.

2. External anchor missing or unverifiable

   • Detect: seal exists but no anchor artifact; anchor proof fails verification.
   • Respond: block promotion of high-impact changes; emit incident artifact; re-run anchoring pipeline.

3. Poisoning of learning signals / adversarial telemetry

   • Detect: replay reports show FP increase or catastrophic boundary regression; outlier actors dominate support.
   • Respond: require quorum + replay + human approval; quarantine candidates; record a ShadowReceipt for the rejected promotion.

4. Overblocking / drift into refusal

   • Detect: trend in false positives; rising “blocked” outcomes on benign workloads.
   • Respond: rollback via new policy receipt; require replay validation before relaxation is promoted.

5. Clock skew / timestamp ambiguity

   • Detect: non-monotonic timestamps, ordering anomalies in seals.
   • Respond: anchor by content ordering (stable sort keys); treat timestamps as metadata; include row ids/hashes in sealing.

6. Trace discontinuity

   • Detect: tool/MCP/proof artifacts lacking trace_id where expected.
   • Respond: enforce trace propagation at call sites; treat missing trace links as audit gaps.

Versioning

All seal bundle formats MUST include a format string (e.g., vm-ouroboros-seal-v0). Any breaking change requires a new version and must be documented as an auditable artifact.