vde 0.1.0

Validation and Drift Engine — runtime execution integrity observer for distributed AI agent systems

VDE — Validation and Drift Engine (Observer Tier)

Reference implementation of the VDE software observability layer for runtime execution integrity in distributed AI agent systems.

What This Is

This repo implements the software observer tier (Tier 2) of the VDE mitigation architecture. It instruments agent workflows to capture intent declarations and execution traces, reconstructs execution graphs per trace, and computes a drift score reflecting divergence between declared intent and actual execution. It is not a standalone security tool — it is the observability foundation for the VDE enforcement architecture described in the research paper.

Research Background

Reference: "Structural TOCTOU Vulnerabilities in AI Agent Frameworks: Analysis, Formalization, and a Hardware-Enforced Mitigation Architecture" (Equinibrium, 2026). The paper describes a three-tier mitigation taxonomy: Tier 1 (application-layer controls), Tier 2 (SW-only ASR), and Tier 3 (HW-enforced ASR). This repository implements instrumentation and drift detection aligned with Tier 2.

Architecture

Agent (instrumented with SDK)
        ↓
VDE API  POST /ingest
        ↓
PostgreSQL (JSONB event store)
        ↓
Drift Engine  reconstruct_graph() / calculate_drift()
        ↓
Streamlit Dashboard

VDE/schema.py — Pydantic models for event types (IntentEvent, ExecutionEvent, StateTransitionEvent) VDE/sdk.py — VDECollector class with async HTTP logging and @vde_trace decorator VDE/api.py — FastAPI ingestion endpoint with PostgreSQL storage VDE/engine.py — DriftDetectionEngine for graph reconstruction and drift calculation VDE/dashboard.py — Streamlit dashboard for visualizing intent vs execution drift

Quickstart

git clone https://github.com/LelloOmwei/VDE.git
cd VDE
pip install -r requirements.txt
export DATABASE_URL=postgresql://user:password@localhost/vde
uvicorn VDE.api:app --reload
streamlit run VDE/dashboard.py

SDK Usage

from VDE import VDECollector, vde_trace, IntentEvent
import asyncio

# Initialize collector
collector = VDECollector(endpoint_url="http://localhost:8000/ingest")
await collector.start()

# Use decorator for automatic logging
@vde_trace("fetch_weather_step")
async def fetch_weather(location: str):
    # Agent step that calls external API
    response = await http_client.get(f"/weather?loc={location}")
    return response.json()

# Manual intent logging
intent = IntentEvent(
    trace_id="trace-123",
    step_id="manual_step",
    expected_action="process_data",
    inputs={"source": "external_api"}
)
await collector.log_intent(intent)

Drift Detection

• Missing steps: Steps declared in intent but not present in execution trace
• Extra steps: Steps executed without corresponding intent declaration
• Reordering: Same steps executed in different sequence order than declared
• Status mismatches: Execution steps that failed or encountered errors

The drift score is a weighted 0–100 metric where higher values indicate greater divergence between intent and execution.

Scope and Limitations

This tier provides observability and drift detection but does not enforce execution blocking. Enforcement requires the ASR (Authorized State Representation) layer. SW-only ASR (TPM/HSM-backed) and hardware-enforced tiers are not included in this repository.

IP Notice

The VDE architecture, including the Authorized State Representation (ASR) model, Scoped System State Version ID (S-SSVID), and associated enforcement mechanisms, is covered by a patent pending filing by Equinibrium s.r.o. This repository contains the open-source observer tier only. Commercial licensing inquiries: [e-mail]

Citation

@techreport{equinibrium2026toctou,
  title     = {Structural TOCTOU Vulnerabilities in AI Agent Frameworks: Analysis, Formalization, and a Hardware-Enforced Mitigation Architecture},
  author    = {Equinibrium s.r.o.},
  year      = {2026},
  institution = {Equinibrium s.r.o.},
  url       = {https://equinibrium.eu}
}