The Immutable Evidence Ledger: Capture, Events and Snapshots

The evidence ledger is a write-once, append-only record: one timeline per comparable, in every study, that never edits or deletes what it has written. It is strictly per-comparable — study-level governance appears instead as study audit-log milestones — and it is the backbone of the audit packet and of the accept-reject defense.

The append-only rule

Plan feature: This capability requires the evidence_repository plan feature (see Plan Features).

Events are never updated or deleted through the product. A wrong event is corrected by writing a new one; the sequence — not the latest value — is the record. One documented exception: when a study’s analysis is re-run, the study’s comparable set is replaced, and the comparable-scoped events (and snapshots) for the old set are removed and re-created with the new run. Study-level snapshots survive a re-run. Everything else is append-only, in the study and in the packet.

The event types

Seven event types make up the vocabulary:

Event	Label	Severity	How it is written
AI_RECOMMENDATION	AI Recommendation	info	Automatic — one per newly saved comparable, the AI rationale as the recorded reason, actor SYSTEM
DATA_CAPTURE	Evidence Captured	info	Automatic when a comparable-scoped snapshot is created (source URL as the reason)
ANALYST_VERIFIED	Analyst Verified	success	A reviewer records it in the dialog after confirming the disposition
MANAGER_REVIEW	Manager Reviewed	success	A reviewer records it in the dialog — no workflow step writes it
MANAGER_OVERRIDE	Manager Override	warning	Automatic on the workflow’s override paths; also selectable in the dialog, where the justification note is enforced
PARTNER_REVIEW	Partner Reviewed	success	A reviewer records it in the dialog — no workflow step writes it
PARTNER_LOCK	Partner Locked	danger	A reviewer records it in the dialog; the lock itself is a study audit-log milestone, not a ledger event

The severity is what colours the timeline dot in the review UI: info and success for the routine, warning for the override, danger for the lock.

The per-event fields

Every event row carries the same identity block:

Field	What it records
Comparable	The company the event belongs to (the ledger has no study-level events)
Event type	One of the seven above
Actor	Who wrote it — user and role, or SYSTEM for auto-recorded events
Occurred at	The UTC timestamp
Rationale	The recorded reason for the event
Justification notes	The reviewer’s written justification — mandatory for a dialog-recorded MANAGER_OVERRIDE (422 when missing); the override paths in the workflow always fill it, generating a default note when the reason is left blank

How the ledger fills itself

Three system paths write events without anyone using the record-event dialog, which is why a fresh study’s ledger is never empty:

• AI screening — the run’s comparable-persistence step appends one AI_RECOMMENDATION event per comparable in the same transaction that inserts the comparable, so the disposition and its reason are recorded atomically.
• Captures — creating a comparable-scoped snapshot appends DATA_CAPTURE in the same step.
• Overrides — both override paths in the workflow (a single row on the review grid, and the committed batch) append MANAGER_OVERRIDE per comparable with the verdict transition as the rationale (previous verdict to new verdict) and the reviewer’s reason as the justification; an empty reason is filled with a generated note naming the comparable. Reverting an override appends no ledger event, though it still writes a study audit-log row.

The manual record-event dialog covers the same vocabulary for the events a reviewer writes by hand.

From ledger to defense

The ledger is what makes the packet defensible:

• The audit packet embeds the ledger as one top-level timeline.json, every event tagged with its comparable id, alongside study.json, audit_logs.json and the captures. A company’s own folder holds its decision record and its snapshots; you read its events by matching the comparable id in the timeline.
• The accept-reject defense is a ledger reading: every accept and reject on the grid has a recorded reason, every override has a mandatory justification, and the sequence proves the order in which the file was built. The TPO’s question — why was this company kept or dropped, and who decided — is answered by two rows.

FAQ

Can I delete or edit an event I entered wrong? No. Write the correcting event with its justification; the pair, in order, is the record.

Where else does the ledger surface? In the Audit Trails module it is merged into the override micro-ledger and the forensic search, as the source of the manager-override, analyst-verified and data-capture rows there.

Is the ledger tenant-isolated? Yes — every read and write is tenant-scoped, and the Superadmin’s view is scoped to their own studies.