> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pensionsportal.ie/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Auditability

> Audit trail design for AI-generated content in PensionsPortal.ie

IORP II requires that all regulated actions are traceable and attributable. This page documents how AI-generated content is audited throughout its lifecycle — from generation to broker approval to execution.

## Audit Trail Overview

```
1. AI generates proposal/draft
   → change_proposals record created (modelId, generatedAt, proposedChanges, citations)

2. Broker reviews
   → UI displays proposal, citations, required attestations

3. Broker approves or rejects
   → change_proposals updated: status, reviewedBy, reviewedAt, completedAttestations

4. Change executed (if approved)
   → Domain event fires
   → audit_logs entry: action, entityType, entityId, previousState, newState

5. Advice record created
   → advice_records table: linked to member, scheme, adviser, SoS document
```

## Change Proposals Table

The `change_proposals` table is the primary AI audit record:

```typescript theme={null}
{
  id: "cuid2",
  brokerId: "broker-001",
  schemeId: "scheme-abc",
  memberId: "member-xyz",
  entityType: "Member",
  entityId: "member-xyz",
  proposedAction: "FundSwitch",
  proposedChanges: {
    currentFundChoiceId: "fund-old",
    newFundName: "Zurich Prisma 4",
    newRiskRating: 4,
  },
  citations: [
    { text: "Fund is appropriate for moderate risk profile", source: "CPC 2012, Chapter 5" },
  ],
  requiredAttestations: [
    { id: "suitability", label: "...", checked: false },
  ],
  modelId: "claude-sonnet-4-20250514",
  generatedAt: "2026-01-15T10:00:00Z",
  status: "Approved",
  reviewedBy: "user-broker-admin",
  reviewedAt: "2026-01-15T10:15:00Z",
  completedAttestations: [
    { id: "suitability", label: "...", checked: true },
  ],
  expiresAt: "2026-01-22T10:00:00Z",
}
```

## Advice Record Linkage

SoS drafts generated by AI are linked to advice records in `advice_records`:

```typescript theme={null}
{
  id: "advice-001",
  memberId: "member-xyz",
  schemeId: "scheme-abc",
  adviserId: "user-broker-admin",  // named adviser — CPC requirement
  adviceDate: "2026-01-15",
  adviceType: "FundRecommendation",
  changeProposalId: "proposal-001", // ← links to AI generation record
  sosDocumentId: "doc-001",         // ← links to final approved SoS
  cpcCompliant: true,
  mccCompliant: true,
}
```

## What Is NOT Logged

AI prompt content is deliberately not stored in audit logs:

* **System prompts** are code — versioned in git, not in the database
* **User message content** is not persisted (may contain personal data)
* **AI response content** is captured only through the structured `proposedChanges` delta and the `sosDocument`

This prevents audit logs from becoming a secondary store of personal data sent to AI providers.

## Model Version Tracking

`change_proposals.modelId` records the exact model used for each generation. This enables:

* Retrospective review if a model version is found to have produced non-compliant output
* Support for model deprecation audits — find all proposals generated by a deprecated model
* Compliance reporting on AI usage across the platform

```sql theme={null}
-- Find all proposals generated by a specific model version
SELECT COUNT(*), status FROM change_proposals
WHERE model_id = 'claude-sonnet-4-20250514'
GROUP BY status;
```

## Regulatory Compliance

The AI audit trail satisfies the following regulatory requirements:

| Requirement                                     | Source                 | How Satisfied                                    |
| ----------------------------------------------- | ---------------------- | ------------------------------------------------ |
| Actions must be attributable to a named person  | CPC 2012, MCC 2017     | `reviewedBy` field in `change_proposals`         |
| Advice records must be retained 6 years         | CPC 2012               | `advice_records` table with `audit_logs` backing |
| AI-assisted decisions must have human oversight | DORA Article 28        | Human-in-the-loop approval before execution      |
| Tamper-evident audit trail                      | IORP II / Pensions Act | Append-only `audit_logs` table                   |

## SuperAdmin Audit Access

SuperAdmin users can query the full AI activity across all tenants for platform-level compliance reviews. All such accesses are themselves audit-logged.