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:
```json
{
  "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):
```json
{
  "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.