Evidence

Evidence is the context gathered to inform policy evaluation. When a LIM evaluates an Intent, it considers both the Intent itself and the evidence collected about it.

What Is Evidence?

Evidence provides context that policies need to make decisions:

interface EvidenceBundle {
  // Agent context
  agent: {
    id: string;
    trustScore: number;
    category: string;
    recentActivity: ActivitySummary;
  };

  // Resource context
  resource: {
    type: string;
    sensitivity: string;
    owner: string;
    lastModified: string;
  };

  // System context
  system: {
    currentLoad: number;
    healthStatus: string;
    activeIncidents: string[];
  };

  // Custom context
  custom: Record<string, unknown>;
}

Evidence Types

Automatic Evidence

ΔOS automatically collects certain evidence for every Intent:

User-Provided Evidence

Include additional context when submitting Intents:

const intent = await deltaos.intents.create({
  action: 'deployment.release',
  resource: 'production/api',
  parameters: { version: '2.1.0' },
  context: {
    // Custom evidence
    testsPassRate: 0.98,
    canaryMetrics: {
      errorRate: 0.001,
      latencyP99: '45ms'
    },
    approvals: ['eng-lead', 'qa-lead'],
    changeTicket: 'CHG-1234'
  }
});

External Evidence

ΔOS can collect evidence from external systems:

await deltaos.evidence.registerSource({
  id: 'vulnerability-scanner',
  type: 'http',
  endpoint: 'https://scanner.internal/api/check',
  collectFor: ['deployment.*'],
  timeout: '2s'
});

When a deployment Intent is submitted, ΔOS queries the scanner and includes results in evidence.

Evidence Collection

Collection Flow

Intent Submitted
       ↓
Identify Required Evidence
       ↓
Collect in Parallel
       ↓
Bundle with Intent
       ↓
Pass to LIMs

Collection Timing

Evidence is collected before LIM evaluation:

Collection Timeout

Evidence collection has a timeout. If a source doesn't respond:

deltaos.evidence.configure({
  timeout: '500ms',          // Per-source timeout
  fallbackOnTimeout: true,   // Use cached/default values
  requireAll: false          // Proceed without missing evidence
});

Using Evidence in Policies

Built-in Evidence Fields

// Policy using agent trust score
await deltaos.policies.create({
  name: 'trust-gate',
  conditions: {
    'evidence.agent.trustScore': { lt: 0.5 },
    action: 'payment.*'
  },
  judgment: 'escalate',
  message: 'Low-trust agent attempting payment'
});

Custom Evidence Fields

// Policy using custom evidence
await deltaos.policies.create({
  name: 'deployment-gate',
  conditions: {
    action: 'deployment.release',
    'context.testsPassRate': { lt: 0.95 }
  },
  judgment: 'block',
  message: 'Test pass rate below 95%'
});

Evidence Expressions

// Complex evidence conditions
await deltaos.policies.create({
  name: 'high-risk-combination',
  conditions: {
    action: 'data.export',
    any: [
      { 'evidence.resource.sensitivity': 'high' },
      { 'context.recordCount': { gt: 10000 } }
    ],
    'evidence.agent.category': 'autonomous'
  },
  judgment: 'escalate'
});

Evidence in LIMs

Custom LIMs access evidence during evaluation:

const myLIM = defineLIM({
  id: 'custom-evaluator',

  // Declare what evidence is needed
  requiredEvidence: ['agent.trustScore', 'resource.sensitivity'],
  optionalEvidence: ['context.approvals'],

  evaluate: async (intent, evidence) => {
    // Use automatic evidence
    const trustScore = evidence.agent.trustScore;

    // Use resource evidence
    const sensitivity = evidence.resource.sensitivity;

    // Use custom evidence (may be undefined)
    const approvals = evidence.context?.approvals || [];

    if (sensitivity === 'high' && trustScore < 0.8 && approvals.length === 0) {
      return {
        judgment: 'escalate',
        reason: 'High sensitivity resource, low trust, no approvals'
      };
    }

    return { judgment: 'allow' };
  }
});

Evidence Recording

All evidence is recorded with judgments:

const judgment = await deltaos.judgments.get(judgmentId);

console.log(judgment.evidence);
// {
//   agent: { trustScore: 0.85, ... },
//   resource: { sensitivity: 'medium', ... },
//   context: { approvals: ['eng-lead'], ... },
//   collectedAt: '2025-01-25T10:30:00Z'
// }

This enables:

• Replay — Re-evaluate with original evidence
• Audit — Understand why decisions were made
• Debug — Identify missing or incorrect evidence

Evidence Replay

Verify decisions with original evidence:

const replay = await deltaos.audit.replay(intentId);

console.log(replay);
// {
//   originalJudgment: 'allow',
//   replayJudgment: 'allow',
//   match: true,
//   evidenceUsed: { ... }
// }

Evidence Sources

Registering Sources

await deltaos.evidence.registerSource({
  id: 'user-database',
  type: 'query',
  query: 'SELECT risk_level FROM users WHERE agent_id = :agentId',
  collectFor: ['payment.*'],
  cache: { ttl: '5m' }
});

Source Types

Source Health

const sourceHealth = await deltaos.evidence.health();
// {
//   sources: [
//     { id: 'user-database', status: 'healthy', latencyP99: '12ms' },
//     { id: 'scanner', status: 'degraded', latencyP99: '450ms' }
//   ]
// }

See Also

• Intent — What evidence is collected for
• LIMs — How evidence is used
• Judgments — Where evidence is recorded