Evidence Packs and Audit Events
Evidence Packs and Audit Events
- Understand runtime authorization decisions and Proof-of-Mandate evidence.
- explain what evidence must preserve for later review
- distinguish raw logs from structured audit evidence
- understand how evidence packs support governance and incident review
Evidence is what makes authorization reviewable. A system can return allowed: true, but that alone does not explain who delegated authority, what action was requested, which constraints were evaluated, whether the mandate was current, or why a verifier accepted the action. Mandaitor's evidence model turns runtime decisions into artifacts that developers, reviewers, counterparties, and governance teams can understand.
An audit event is a structured record of a relevant lifecycle or verification event. An evidence pack is a curated set of records that helps someone understand a mandate, a decision, an incident, or a review period.
Logs, audit events, proof, and evidence packs
| Artifact | What it usually contains | Who uses it |
|---|---|---|
| Technical log | Request IDs, errors, timing, infrastructure details. | Developers and operators. |
| Audit event | Actor, action, mandate, lifecycle event, decision reason. | Security, compliance, product owners. |
| Proof-of-Mandate | Verifiable evidence linked to a mandate and decision. | Relying systems and external counterparties. |
| Evidence pack | Aggregated proof, events, context, explanations, and an export manifest. | Auditors, incident responders, governance reviewers. |
| Export manifest | Export identifier, requester attribution, coverage summary, and recomputable digests for the mandate snapshot, event chain, proof tokens, and manifest. | Auditors, counterparties, security reviewers, and offline verifier workflows. |
The evidence pipeline
Evidence should be created as a by-product of the control, not assembled only after something goes wrong. The pipeline begins when an agent proposes an action and continues through verification, execution, and review.
| Evidence field | Why it matters |
|---|---|
| Principal | Shows whose authority was delegated. |
| Delegate | Shows which agent, service, workflow, or human acted. |
| Mandate | Links the action to a defined authority boundary. |
| Action | Shows what was requested, not only that a request occurred. |
| Resource | Shows what object, account, project, or record was affected. |
| Constraints | Shows which boundaries were evaluated. |
| Decision | Records allow, deny, approval, or missing-context result. |
| Reason code | Makes outcomes understandable and testable. |
| Timestamp and lifecycle status | Supports chronology, expiry, revocation, and incident analysis. |
Evidence packs as explanations
Mandaitor evidence packs include an export_manifest so a reviewer can verify not only the event chain, but also the exact export envelope that was handed over for review. The manifest records a stable export identifier, the export timestamp, the normalized requester derived from RBAC context, coverage metadata, and hashes for the pack sections that matter most for tamper detection.
| Manifest field | Review purpose |
|---|---|
export_id and generated_at | Identify one concrete export operation and its chronology. |
generated_by | Preserves requester subject, tenant, authentication method, roles, and permissions when available. |
coverage | States the mandate, tenant, event count, optional event filter, and schema version covered by the export. |
digests | Provides recomputable hashes for the mandate snapshot, event chain, proof tokens, and manifest itself. |
hash_algorithm | Records the algorithm used by the active Core hashing abstraction. |
Every evidence-pack export also appends an EVIDENCE_PACK_EXPORTED audit event to the mandate event ledger. The event captures the export identifier, manifest hash, case-log hash, event count, schema version, and optional event filter so the export itself becomes part of the append-only governance history. In Wave 4, the same manifest integrity signal is published into trust data and displayed in the Trust Operations cockpit, allowing operators to see verifier status without opening the full pack.
An evidence pack should be readable by a human who was not present when the action happened. It should provide enough context to understand the authority boundary, the verification decision, the action outcome, and any exceptions. It should not force the reviewer to reconstruct meaning from raw application logs alone.
| Evidence pack section | Purpose |
|---|---|
| Executive summary | Gives a short answer to what happened and why it matters. |
| Mandate context | Shows principal, delegate, scope, constraints, and lifecycle. |
| Verification timeline | Shows the relevant decisions in chronological order. |
| Proof material | Provides proof references or validation outputs. |
| Export manifest | Provides requester attribution, coverage metadata, and recomputable digests for offline integrity checks. |
| Export audit event | Records that an evidence pack was exported, including the export and manifest identifiers. |
| Exception notes | Explains denials, approvals, missing context, or escalations. |
| Reviewer actions | Records follow-up decisions, policy changes, or closure. |
Good evidence is selective
Evidence should be sufficient, not unlimited. A runtime verifier may only need minimal proof to accept a tool call. A compliance reviewer may need a richer pack. A counterparty may need proof without internal policy details. This means evidence design should consider audience and purpose.
| Audience | Needs | Avoid |
|---|---|---|
| Runtime verifier | Fast proof status and decision result. | Exposing unnecessary internal details. |
| Developer | Request context and reason codes. | Hiding debugging information behind opaque labels. |
| Compliance reviewer | Mandate, constraints, timeline, and proof references. | Raw logs without explanation. |
| External counterparty | Verifiable proof and accepted claims. | Full internal policy export unless required. |
Practice check: build a reviewable evidence pack
Evidence-pack reconstruction
A customer-support agent updated a high-value customer's renewal terms. The business outcome was acceptable, but a reviewer now needs to understand whether the agent had authority, whether the customer record matched the mandate, and whether the action was inside policy.
Evidence packs should make the authority path inspectable. They should not force reviewers to infer authority from unrelated logs.
- Select the minimum evidenceChoose the mandate identifier, actor, delegate, action, resource, policy version, decision, reason, timestamp, and outcome fields that must be present.
- Remove noisy dataList which chat transcript details or unrelated tool outputs should not be included in the pack unless they explain the authority decision.
- Write the reviewer questionFrame the one question the evidence pack should let a non-engineer answer in under two minutes.
- Completeness
- The evidence pack can connect the action to mandate, policy, context, and outcome.
- Selectivity
- The pack avoids becoming a raw log dump and includes only review-relevant data.
- Explainability
- A reviewer can understand the authorization story without replaying the whole system.
What is the main difference between an audit log and a Mandaitor-style evidence pack?
- An audit log is always public, while an evidence pack is always private.
- An audit log records events; an evidence pack assembles the authority, policy, decision, reason, and context needed for review.
- An evidence pack replaces the need to store timestamps or actor identifiers.
Reveal answer
An audit log helps show that events occurred. An evidence pack goes further by selecting and organizing the authority evidence needed to understand why the action was allowed, denied, or escalated. In Mandaitor, the export manifest and the corresponding EVIDENCE_PACK_EXPORTED audit event also make the export operation itself reviewable.
What to read next
Read Compliance Dashboard Explained to understand how evidence becomes visible as posture and gap signals. Read Governance, Risk, and Compliance to understand how evidence supports oversight and continuous improvement.
Save your learning progress
Mark this lesson as complete to update the Academy overview without requiring an account.