Developer documentation

Evidence

Last reviewed 31 August 2026

Evidence

Every decision is written to a durable, tenant-scoped record with the

stage-by-stage verdicts that produced it. The purpose is the incident review six

months later, not a dashboard today.

What is recorded

identity, intent, action, resource, tenant, policy and policy version, risk,

verification, approval, decision, enforcement, execution, result, timestamp,

correlation id.

Retrieving it

cain inspect                       # recent decisions
cain inspect --chain <cor_...>     # one correlated agent run, in order
cain explain <decision-id>         # stage by stage, with the policy version
cain audit --decision <id>         # the signature covering it
cain audit                         # who has read evidence

Searchable by decision id, agent, tenant, action, time, resource and correlation

id.

Correlation

Calls made during one agent run share a correlation id, so a run reads as a

sequence rather than scattered rows. cain inspect --chain reports the outcome,

where it stopped, and -- importantly -- would_block_if_enforcing: what a shadow

deployment would have refused.

Signatures

cain audit --decision <id>

Decisions are signed so alteration is detectable. Signing is deterministic:

the same decision signs identically every time, which is what makes a changed

signature meaningful.

This is tamper-evidence, not tamper-proofing, and not third-party notarisation.

The API response says so in its own scope_note field.

Reading evidence is itself recorded

"Who looked at this decision" is the second question an investigation asks.

cain audit shows that log, including which credential type was used.

A failure to write an access-audit row never fails the read -- turning a logging

fault into an outage would be worse than the gap it closes.

Retention

evidence:
  enabled: true
  retain_days: 90

Decisions are retained for the life of the account by default so they remain

available for review. See the DPA for deletion.