Skip to main content

VCAL Audit

VCAL Audit is an optional commercial evidence service for retaining AI Cost Firewall execution evidence outside the gateway process.

AI Cost Firewall sends vcal.evidence.event schema version 1.1 records to Audit through a bounded, batched HTTP delivery path. Audit persists evidence, reconstructs request traces, applies licensed retention policies, exports retained evidence, and verifies its authoritative tamper-evident record chain.

Integration point​

AI Cost Firewall
  -> bounded evidence queue
  -> batched HTTP delivery
  -> POST /v1/events/batch
  -> VCAL Audit
      -> trace reconstruction
      -> retention / export / verification
      -> VCAL Compliance

Typical AI Firewall configuration:

audit_enabled true;
audit_url http://vcal-audit:8092;
audit_api_key your-audit-key;
audit_producer_instance_id ai-firewall-01;

Basic service checks:

curl http://localhost:8092/healthz
curl http://localhost:8092/readyz
curl http://localhost:8092/version
curl http://localhost:8092/metrics

/healthz reports process liveness. /readyz also reflects Audit runtime and SQLite readiness and should be used by container orchestration for service readiness.

Protected Audit API calls use the X-API-Key header:

curl -s \
  -H "X-API-Key: $AUDIT_API_KEY" \
  "http://localhost:8092/v1/events?limit=20&after_sequence=0"

Events and batches​

An event is one individual evidence record describing something that happened while a request was processed. Examples include:

request.received
guard.security.request.scan
guard.privacy.request.scan
cache.lookup.completed
upstream.request.sent
upstream.response.received
request.completed

A batch is only a transport unit: multiple evidence events sent to Audit together in one ingestion request.

many evidence events
  -> one buffered batch
  -> POST /v1/events/batch

The distinction is useful in Audit graphs:

  • Events show the actual volume of retained evidence records.
  • Batches show how that evidence reached Audit and therefore help explain ingestion efficiency and delivery behavior.

For example, 1,000 events delivered in 20 batches means Audit retained 1,000 evidence records while the producer used only 20 batch-ingestion requests.

A single AI request normally generates multiple evidence events, so event volume is expected to be substantially higher than request volume.

Trace reconstruction​

Events belonging to the same AI request share a stable trace_id.

A trace can be reconstructed through the Audit trace API:

curl -s \
  -H "X-API-Key: $AUDIT_API_KEY" \
  "http://localhost:8092/v1/traces/<trace_id>"

Every trace that emits request.received must end with exactly one terminal lifecycle event:

request.completed

or:

request.failed

Delivery and backpressure​

The Audit delivery path is asynchronous and bounded.

AI Cost Firewall batches evidence events and retries transient delivery failures. VCAL Audit can apply bounded ingestion admission and return:

429 Too Many Requests
Retry-After: 1

when ingestion capacity is exhausted.

AI Cost Firewall treats Audit backpressure as retryable and honors Retry-After.

If delivery retries are exhausted, evidence that remains only in the current in-memory delivery queue cannot be replayed after the AI Firewall process restarts.

Integrity and retention​

VCAL Audit maintains an authoritative SHA-256 record chain independently of producer-supplied event hashes.

Licensed retention policies can physically prune expired authoritative records while preserving continuity through a persistent retention anchor. Chain verification starts from that retained anchor rather than incorrectly resetting to GENESIS.

Full-chain verification uses a dedicated SQLite verification connection and a consistent read snapshot so verification does not hold the primary store mutex and serialize ordinary Audit query traffic.

Licensing​

VCAL Audit licensing can independently control capabilities such as:

  • evidence ingestion
  • trace and event queries
  • NDJSON export
  • chain verification
  • maximum accepted events per day
  • retention period

AI Cost Firewall integration does not require every Audit capability to be enabled.

See Evidence events, Configuration, and Troubleshooting.

note

This page intentionally provides the AI Cost Firewall integration overview. Full VCAL Audit API, storage, licensing, retention, verification, export, and operational documentation is maintained separately.