Audit Trails: The Complete Study Chronology

Audit Trails is the governance and forensics layer of the product: it does not rewrite history, it aggregates the append-only rows the rest of the platform already writes — the study audit log, the evidence ledger, and the access log. Its one persisted write of its own is the reviewer-override row you log from the overrides tab; the access and security rows it displays are appended by the auth, team, admin, profile, study-deletion and API-key flows through the same shared recorder. Nothing in the module edits an existing row. Seven tabs sit over the aggregate: Overview, Lifecycle Chronology, Workflow Health, Override Micro-Ledger, AI Ground Truth, Access & Security (admin-only) and Forensic Search.

What the chronology records

Six action types make up the study lifecycle record — and the six the action-type filter offers:

Action	What it captures
Study creation	The study coming into existence
Status transition	Every move between workflow states, with the from and to states
Rejection reason change	The reasons attached to a rejection
Assignment change	A study being (re)assigned to a reviewer
Reviewer override	A human overriding or altering a recorded decision
Study update	Edits to the study’s data, classified as financial or narrative

The chronology table itself is not filtered to those six: it returns every audit-log row on the studies you can see, so other stored action types show up in the stream without being offered as a filter — Study Report Requested, the approval click while the study sits in review, is the one you will notice. The label is derived from the stored action type, not from a lookup table.

Every entry carries the study, the actor (display name and the role captured on the row — the chronology payload has no actor email), the action label, the previous and new value where there is one, the justification notes, the timestamp, and — where the entry links to an AI decision — the ai_reason_id of the AI reason being overridden.

Answering the TPO question

The chronology exists to answer one question in the order the work happened: show me the work as it happened. For any study, the entries reconstruct the file’s biography — created by whom, when it entered review, what the reviewer did and wrote, where it was rejected and why, who signed it off, which dispositions were overridden and with what justification. The study-scoped state-log view narrows the same rows to pure status transitions, oldest first, with human-readable state labels on both ends — the spine of the study’s state machine, on its own. It returns a single page of rows and no page count, so widen the date filter rather than expecting to page through it.

The dashboard

The module’s front door is a KPI summary across the studies you can see: studies tracked, status transitions logged, active state spans and how many of those are past the 48-hour line (see bottleneck tracking), transitions into Rejected, override rows — counted over the same merged sources as the micro-ledger, so verifications and captures are inside that number too — and failed logins and ledger exports over the last 30 days. Those last two are computed only for Firm Admin and Superadmin views; the cards are rendered for everyone and read zero otherwise. Summary and filter options are served from the analytics cache, so the numbers can lag the tables briefly. It is the health check before you open any tab.

The AI ground-truth registry

The AI Ground Truth tab is a cross-study registry of the standardized AI decision reasons carried by your comparables. Each reason gets an ai_reason_id: the first 16 hex characters of a SHA-256 over tenant + reason text, so the same reason maps to the same identifier across studies, and overrides can cite it. The tab shows total comparables scanned, distinct reasons, and per-reason company counts with first/last seen timestamps. The “recently-accessed reasons” panel reports hit counts and recency from an in-process LRU (capacity 256 IDs) — it is a cache, not a stored ledger, so those counts reflect the running server, not history.

Forensic search across studies

The search tab is the cross-study instrument: one query across all three sources at once.

• Sources merged — study audit rows, the override micro-ledger’s evidence events, and (for admin views) the access log, each entry badged with its source (study_transition, override, or access). Audit rows whose action type is an override or a study update are badged as overrides and carry the derived category; the rest badge as study transitions.
• What it matches — free text matches the action label, the study name, the actor name or email, the target email, the justification notes and the previous/new values. It does not match ai_reason_id.
• The filters — actor, study, action type, date range and free text apply across the merged sources; event type narrows the access rows only, and the category filter belongs to the override micro-ledger rather than to this view. Results are newest first and paginated.

Typical uses: every override by reviewer X in a period, every entry mentioning comparable Z, everything recorded against one study. Access rows carry no study reference, so in a merged result set the study cell is blank for them — they are matched by actor, email and free text instead.

Access levels

Capability	Who
Chronology, workflow, overrides, ground-truth registry, search	Manager, Partner, Firm Admin, Superadmin
Access and security logs	Firm Admin, Superadmin only
Ledger export	Partner, Firm Admin, Superadmin
Recording an override row	Any authenticated member who can reach the study
Superadmin scoping	All views scoped to the superadmin’s own studies; access logs self-scoped

Analysts have no access to the module: the backend returns 403 on every audit-trails read, and the export and access controls simply never render for a role that does not hold them.

FAQ

Does the module ever modify history? No. Aggregation is read-only; the only rows written from here are the reviewer-override row you log from the overrides tab, and the access/security events the sign-in and administration flows append. Those are new rows, never edits to existing ones.

How is this different from the dashboard activity feed? The feed is the readable face of recent events on the dashboard; the chronology is the complete, filterable, exportable record of the same rows.

Where do the override rows come from? Two append-only sources, merged: the study audit log (reviewer overrides, study updates) and the evidence ledger (manager overrides, analyst verifications, data captures) — see the override ledger.