Evidence Ledger

Signed decision records that prove who authorized what, under which policy, at what cost — not logs, evidence.

Overview

The Evidence Ledger is planned for Phase 2 of BrainstormRouter's governance roadmap. This page describes the design and API surface. Features marked Coming Soon are not yet available in production.

Logs tell you what happened. Evidence proves it was authorized.

BrainstormRouter's Evidence Ledger captures signed, immutable decision records for every significant action an AI agent takes through the platform. Each record answers five questions that auditors, compliance teams, and legal counsel need answered:

1. Who — Which agent, identified by SPIFFE URI
2. Under what policy — Which policy version was active at decision time
3. With what approval — Human approval, delegated authority, or autonomous
4. What decision — Route selection, model choice, budget allocation
5. What cost — Actual tokens consumed and dollars spent

Why evidence, not logs

Logs are mutable, unstructured, and designed for debugging. They answer "what happened?" but not "was it authorized?" Evidence records are:

• Signed — Each record includes a cryptographic signature from the gateway

that processed the request, preventing tampering after the fact.

• Structured — Fixed schema with mandatory fields. No free-text ambiguity.
• Policy-versioned — Every record references the exact policy version that

authorized the action. If the policy changes tomorrow, yesterday's evidence still proves yesterday's action was valid under yesterday's rules.

• Immutable — Once written, records cannot be modified or deleted through

the API. Retention is governed by tenant configuration.

What gets captured

Every completions request that passes through the Guardian middleware generates an evidence record:

Field	Description
agent_id	SPIFFE URI of the acting agent
tenant_id	Tenant that owns the agent
request_id	Unique request identifier
timestamp	ISO 8601 timestamp with timezone
policy_version	Hash of the active policy at decision time
approval_type	autonomous, delegated, or human_approved
model_requested	Model the agent asked for
model_routed	Model the router actually selected
route_reason	Why the router chose this model (strategy, fallback, trust override)
trust_level	Agent's trust level at request time
estimated_cost	Pre-request cost prediction
actual_cost	Post-response actual cost
guardrail_verdicts	Array of guardrail scan results
signature	Ed25519 signature over the record

Coming API Coming Soon

Query evidence records for a specific agent:

const evidence = await client.evidence.list({
  agentId: "agent-001",
  since: "2025-07-01T00:00:00Z",
  until: "2025-07-31T23:59:59Z",
  limit: 100,
});

for (const record of evidence.records) {
  console.log(`${record.timestamp} ${record.model_routed}`);
  console.log(`  Policy: ${record.policy_version}`);
  console.log(`  Trust:  ${record.trust_level}`);
  console.log(`  Cost:   $${record.actual_cost.toFixed(4)}`);
  console.log(`  Signed: ${record.signature.substring(0, 16)}...`);
}

Retrieve a single evidence record by request ID:

const record = await client.evidence.get({
  requestId: "req_abc123",
});

// Verify the signature independently
const valid = await verifyEd25519(record.signature, record.payload, gatewayPublicKey);

Export evidence for a compliance audit:

curl https://api.brainstormrouter.com/v1/evidence/export \
  -H "Authorization: Bearer br_live_..." \
  -d '{"agent_id": "agent-001", "format": "csv", "since": "2025-Q3"}'

Why this matters

Audit

When an auditor asks "show me proof that agent X was authorized to use model Y on date Z," the evidence ledger provides a single signed record — not a stack of log files to correlate.

Compliance

Regulations like EU AI Act Article 12 require "automatic recording of events" for high-risk AI systems. Evidence records satisfy this requirement with structured, signed, policy-versioned data.

Legal

If an AI agent causes damage, the evidence ledger establishes the chain of authorization. Was the agent operating within its policy? Was a human in the loop? What trust level was the agent at? These are questions that matter in litigation.

Cost attribution

Every record captures both estimated and actual cost, making it possible to attribute AI spend to specific agents, tasks, and decisions — not just aggregate usage buckets.

See Governance for the memory audit trail that complements the evidence ledger.