# Tamper-evident audit log

Every action the hub takes goes into one append-only event
log. Module installs, flow runs, approval decisions, channel
switches, daemon restarts — all recorded with the same shape.

## What an event looks like

```
timestamp:     2026-05-08T14:32:11Z
event_id:      ev_01H...
event_type:    flow.completed
flow_name:     extract-summarize
flow_execution: fe_01H...
duration_ms:   1240
module_name:   text.summarize
module_version: 0.1.0
detail:        { engine: "ollama", model_name: "gemma3:4b",
                  model_digest: "sha256:..." }
prev_event_sha256: 6f4e...8b5f
```

The `prev_event_sha256` field is the key. Every new event
hashes its content together with the previous event's hash. To
falsify event N, an attacker would need to rewrite every event
from N+1 onwards — and the chain head would no longer match
what the operator's last verification recorded.

## What "WORM-1" means

WORM-1 is our first WORM (write-once-read-many) tier:

- **Append-only**: the hub never deletes individual events.
  The CLI / RPC has a single batch operation,
  `clear_event_log`, which wipes the channel and seeds a
  `chain.reset` marker carrying reviewer + reason. Refused on
  beta / production channels.
- **Tamper-evident**: the chain reveals any retroactive edit.
  Verification runs end-to-end on every Doctor-page load and
  via `fai admin verify-events`.
- **Self-contained**: SQLite + chain hash is enough; no
  external WORM sink needed.

WORM-2 (Linux append-only file attribute) and WORM-3 (external
WORM sink) are roadmap items, not yet shipped.

## What you'll see in this app

- **Doctor → Event log**: live "chain intact" / "tamper
  detected" indicator with verified-event count. Click "Verify
  now" for an explicit re-check.
- **Audit page**: live stream of recent events with filter
  chips (flow / step / module). Click any row to see the full
  event JSON.
- **Doctor → Daemon files → Audit-DB**: reveals the SQLite file
  in your file manager.

## Reading the chain by hand

If you want to verify outside Studio:

```bash
fai admin verify-events
# Prints "Hash chain intact: N events verified" or names the
# first event whose hash mismatches.
```

The chain is the source of truth — every other audit-related
piece of UI in Studio reads from it.