# Evidence

> Every decision, approval, freeze, promotion and change of access is a record in a hash-chained ledger whose head is signed at intervals. A rewrite shows, and you can check it without trusting us.

Source: https://immiscible.fly.dev/docs/concepts/evidence

Logs written by the system they describe are hard to trust: the same system that made a decision could rewrite the record of it. Immiscible's evidence is built so that a rewrite is visible.

## Three properties

1. **Chained.** Every record names the SHA-256 hash of the record before it. Changing, removing or reordering one breaks the chain at that point.
2. **Checkpointed.** At intervals, and whenever someone asks, the head of the chain is signed with Ed25519 into a checkpoint. A checkpoint you kept proves that the history up to it is the history you were shown, even if every copy we hold were rewritten.
3. **Keyed for the long run.** A bundle carries every public key that ever signed a checkpoint, including retired ones, so a checkpoint from years ago still verifies after rotation.

## What a record holds

An abridged decision record. The envelope fields are exact (the [specification](https://immiscible.fly.dev/docs/security/evidence-spec.md#records) defines them); the payload varies by `kind`.

```json
{
  "schema": "assay.evidence.v1",
  "seq": 4182,
  "id": "rec_0d1c9e",
  "at": "2026-10-04T09:12:44.018Z",
  "prev": "9a0f3c...",
  "kind": "agent_decision",
  "payload": {
    "agentId": "agt_4f2c91a7",
    "decision": "allow",
    "signals": [],
    "subject": { "kind": "agent", "id": "agt_4f2c91a7" },
    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
    "profile": { "version": 7, "hash": "c41e..." }
  },
  "hash": "2b77e1..."
}
```

Payloads hold digests and pseudonyms in place of personal data. Every record carries a **subject** (the agent, person, single sign-on subject, application or key that acted) and the **W3C trace** it belongs to, and every decision records the access profile version and hash it was made under.

## What is recorded

| Area | Kinds include |
|---|---|
| Agents | decisions, settlements, incidents, freezes and lifts, drills |
| Authority | mandates created and revoked, tier changes, sign-offs, overrides |
| Access | applications and their versions, profile changes, allowlists, entitlements, recertifications |
| People | approvals and denials with channel and who decided, reviews and their verdicts |
| Machines | service tokens made and revoked, and every action a token took, by name |
| The card rail | every authorisation, approved or declined, and every clearing |
| The gateway | per-request records: model, cost, data region, budget, routing rule applied |

## Getting it out

- **The bundle.** [`GET /api/w/:wid/evidence/bundle`](https://immiscible.fly.dev/docs/api/get-api-w-wid-evidence-bundle.md): records, checkpoints and keys in one JSON document, or streamed for large workspaces.
- **Checkpoints.** [`POST /api/w/:wid/evidence/checkpoints`](https://immiscible.fly.dev/docs/api/post-api-w-wid-evidence-checkpoints.md) signs the head now. Keep the token it returns somewhere we cannot reach.
- **Machines.** A [service token](https://immiscible.fly.dev/docs/api/authentication.md#service-tokens) with `evidence:read` reads the bundle and the signed scorecard.
- **Your SIEM.** As [OCSF or OpenTelemetry](https://immiscible.fly.dev/docs/guides/siem-export.md), pulled or pushed by signed webhook.

## Verifying it

```bash
node scripts/verify-evidence.mjs bundle.json --keys keys-you-kept.json
```

One file, no dependencies, short enough to read before running. Exit code `0` means everything verified; otherwise the report names the first record that broke and every checkpoint that no longer holds. The format and the verifier are specified in the [evidence specification](https://immiscible.fly.dev/docs/security/evidence-spec.md), and the step by step is in [verifying offline](https://immiscible.fly.dev/docs/security/verifying-offline.md).

> **Important**
> A bundle on its own proves only that it is consistent with itself. Keep the public keys when you start relying on the evidence, or keep checkpoints as they are issued, or both. Either one closes the gap.

## What this is not

Evidence proves the record was not changed after it was written and signed. It does not prove a decision was right, and it does not make anyone compliant with anything. It is evidence a compliance process can rely on; the bundle lists the published record-keeping obligations it supports (for example EU AI Act Art. 12 and Art. 26(6)) as references for whoever writes the compliance file.