Flight Data Recorder (FDR) & Replay CLI

The Flight Data Recorder (FDR) is an opt-in Volidator feature designed for high-assurance AI agent compliance. Instead of trying to force deterministic LLM generation or versioning massive databases, FDR captures the exact environment the agent was exposed to (inputs, outputs, prompt templates, model versions) and securely locks it in an append-only cryptographic ledger.

This guide explains how to configure FDR in your application and perform offline Input-Side Forensic Replays using the Volidator CLI.

---

The Audit Lifecycle

[Production Run] ──► Capture System Prompt, VCR Tool Calls & Alibi
                          │
                          ▼ (commitRun)
                     Compressed Gzip Upload ──► Secure Object Storage
                     Cryptographic Chaining   ──► Immutable Distributed Ledger
                          │
                          ▼ (6 Months Later)
[Auditor Replay] ──► Walk ledger chain to verify integrity
                     Decompress & decrypt cached storage bundle
                     Set VOLIDATOR_REPLAY_MODE=1
                     Re-run agent in air-gapped simulation bubble

---

What is a Flight Data Recorder (FDR) in AI?

In aviation, a Black Box (Flight Data Recorder) does not prevent an event; it records every sensor input, pilot decision, and mechanical state so investigators can reconstruct exactly what happened.

For Autonomous AI Agents, the FDR follows the same design pattern. AI models are inherently non-deterministic: cloud LLM providers update models silently, temperature sampling adds randomness, and live third-party APIs change their responses second-by-second. Trying to achieve deterministic output replay is a myth.

Instead of trying to freeze the entire world, Input-Side Forensic Reconstruction records:

• The System Instruction Set: The exact system prompt and instructions the agent was loaded with.
• The Environmental Inputs: A VCR-style recording of the exact inputs and outputs returned by tools (databases, search APIs, file systems) during the agent run.
• The Provider Alibi: Metadata proving the exact LLM configuration (model ID, seed, and OpenAI system fingerprint) serving the generation.

By storing these inputs in a hash-chained, append-only distributed ledger and zipping the payload in secure object storage, you create a tamper-proof forensic trail.

---

Why it Matters: The Compliance & Business Value

Deploying an FDR is the single most critical step for enterprise compliance when integrating autonomous AI agents:

• EU AI Act (Article 12 - Logging & Traceability): The EU AI Act mandates that high-risk AI systems must automatically record logs throughout their lifecycle. Specifically, these logs must enable the traceability of the system’s functioning to reconstruct execution steps.
• SOC 2 Type II Auditing (Trust Services Criteria CC6.6 & CC7.2): Standard application logs only record that a tool was called. An auditor reviewing an autonomous action (e.g., an agent transferring funds) requires proof of why the decision was made. FDR logs the complete, encrypted context leading up to the transaction.
• ISO 27001 (A.12.4 - Logging & Monitoring): Guarantees that agent behaviors and system compromises (like prompt injection attacks) are completely auditable and cannot be modified retroactively by rogue operators.
• Post-Mortem Debugging & Regression Testing: If an agent executes an incorrect action, developers can download the exact VCR payload, patch the agent’s code locally, and run a replay simulation to verify the fix works—using the exact inputs the agent saw during the live incident.

---

1. Enabling FDR in the SDK

To activate FDR, pass the fdr configuration when initializing VolidatorClient:

import { VolidatorClient } from "@volidator/node";

const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY,
  fdr: { enabled: true } // Opt-in
});

---

2. Instrumenting Your Code

An FDR run consists of three main evidence inputs: VCR Tool wrappers, system prompts, and the model alibi.

A. Wrapping Tools

Wrap external tools, databases, or API functions. Specify an allowList to scrub raw authorization tokens, headers, or cookies before serialization:

const fetchExchangeRates = volidator.fdr.wrapToolForVCR(
  "fetch_exchange_rates",
  async (args) => {
    return await api.get(`/rates?base=${args.base}`);
  },
  runCtx,
  { allowList: ["base"] } // "apiKey" param inside args will be stripped!
);

B. Capturing System Prompts and Model Alibis

Record the system prompt template and model parameters immediately when executing the generation:

// Create the FDR context
const runCtx = volidator.fdr.createRun("run_uuid_999", "project_id_123");

// Record System Prompt
await volidator.fdr.captureSystemPrompt(runCtx, "You are a secure trading assistant...");

// Perform LLM call
const response = await openai.chat.completions.create({
  model: "gpt-4o-2024-08-06",
  seed: 1337,
  messages: [...]
});

// Record Model Alibi
volidator.fdr.captureProviderAlibi(runCtx, {
  modelId: response.model,
  systemFingerprint: response.system_fingerprint,
  seed: 1337
});

C. Committing the Run

At the end of your agent execution, call commitRun() to gzip and secure the evidence bundle in Volidator:

const commitResult = await volidator.fdr.commitRun(runCtx);
console.log(`FDR Run Committed. Chain Hash: ${commitResult.chainHash}`);

---

3. Running an Audit Replay

When an auditor or developer needs to inspect the run, they execute the @volidator/cli tool directly via npx.

Step 1: Resolve Credentials

Expose the Volidator API Key and Encryption Key in your terminal session:

export VOLIDATOR_API_KEY="val_live_xxxxxxxx..."
export VOLIDATOR_ENCRYPTION_KEY="vol-dek-xxxxxxxx..."

Step 2: Run Replay Command

Execute the replay command targeting the audited runId:

npx @volidator/cli replay --run-id run_uuid_999

This sequentially completes the replay checklist:

1. Verifies Ledger Chain Integrity: Fetches the ledger history surrounding the run and validates that no rows have been deleted or modified since the commit.
2. Downloads and Decrypts Bundle: Fetches the gzipped data from secure storage, verifies its SHA-256 hash matches the ledger’s payload hash, and decompresses it locally using your decryption key.
3. Hydrates local VCR Cache: Loads tool inputs and outputs into an in-memory VCR cache proxy.
4. Prints Replay Guide: Shows the captured prompt and LLM alibi metrics.

Step 3: Run the Agent in Simulation Mode

Set VOLIDATOR_REPLAY_MODE=1 in your environment and run your agent runner:

export VOLIDATOR_REPLAY_MODE=1
node src/agent-runner.js

During this execution, your wrapped tools will intercept calls, check the VCR cache for matching arguments hashes, and return historical data instantly without hitting the live internet.