# Quickstart: Audit Log Foundation

**Feature**: 134-audit-log-foundation | **Date**: 2026-03-11

## Scope

This feature turns the existing Audit Log placeholder into a real enterprise Monitoring surface by:

- evolving the current `audit_logs` store into a first-class audit event model,
- consolidating the existing audit writers behind one shared recorder foundation,
- standardizing event taxonomy, actor kinds, target snapshots, summaries, and outcomes,
- instrumenting first-wave governance, backup or restore, operations, and admin-change event sources,
- replacing the placeholder `/admin/audit-log` page with a filterable, summary-first audit list and detail inspection surface,
- enforcing workspace and tenant-safe visibility through `audit.view` and existing target entitlements,
- making retention explicit so audit history is no longer treated as short-lived operational noise.

## Implementation order

1. Expand the audit taxonomy and outcome model, using the current `AuditActionId` registry as the starting point.
2. Design and implement the additive `audit_logs` migration path, including stronger indexes and compatibility-safe backfills.
3. Introduce the shared audit recorder and adapt the existing tenant, workspace, and system loggers to use it.
4. Tighten `AuditContextSanitizer` usage and codify context-shaping rules for summaries, before/after snapshots, and safe metadata.
5. Normalize first-wave workspace and governance audit writes from `WorkspaceMembershipManager`, `SettingsWriter`, findings workflow, and baseline workflows.
6. Normalize first-wave backup, restore, and operation outcome audit writes without changing `OperationRun` lifecycle ownership.
7. Replace the placeholder `App\Filament\Pages\Monitoring\AuditLog` surface with a real workspace-scoped table, filters, badges, and detail inspection affordance.
8. Ensure related target links are canonical and permission-aware through existing navigation helpers.
9. Update retention-related commands or purge flows so durable audit history is no longer deleted as regeneratable noise.
10. Run focused Sail-based tests and Pint.

## Reference files

- [app/Models/AuditLog.php](../../../app/Models/AuditLog.php)
- [database/migrations/2025_12_10_000160_create_audit_logs_table.php](../../../database/migrations/2025_12_10_000160_create_audit_logs_table.php)
- [database/migrations/2026_02_01_002054_add_workspace_id_to_audit_logs_table.php](../../../database/migrations/2026_02_01_002054_add_workspace_id_to_audit_logs_table.php)
- [app/Services/Intune/AuditLogger.php](../../../app/Services/Intune/AuditLogger.php)
- [app/Services/Audit/WorkspaceAuditLogger.php](../../../app/Services/Audit/WorkspaceAuditLogger.php)
- [app/Support/Audit/AuditActionId.php](../../../app/Support/Audit/AuditActionId.php)
- [app/Support/Audit/AuditContextSanitizer.php](../../../app/Support/Audit/AuditContextSanitizer.php)
- [app/Filament/Pages/Monitoring/AuditLog.php](../../../app/Filament/Pages/Monitoring/AuditLog.php)
- [resources/views/filament/pages/monitoring/audit-log.blade.php](../../../resources/views/filament/pages/monitoring/audit-log.blade.php)
- [app/Filament/Resources/OperationRunResource.php](../../../app/Filament/Resources/OperationRunResource.php)
- [app/Filament/Resources/AlertDeliveryResource.php](../../../app/Filament/Resources/AlertDeliveryResource.php)
- [app/Services/Findings/FindingWorkflowService.php](../../../app/Services/Findings/FindingWorkflowService.php)
- [app/Services/Auth/WorkspaceMembershipManager.php](../../../app/Services/Auth/WorkspaceMembershipManager.php)
- [app/Services/Settings/SettingsWriter.php](../../../app/Services/Settings/SettingsWriter.php)
- [app/Console/Commands/TenantpilotPurgeNonPersistentData.php](../../../app/Console/Commands/TenantpilotPurgeNonPersistentData.php)

## Suggested validation commands

```bash
vendor/bin/sail artisan test --compact tests/Unit/Audit
vendor/bin/sail artisan test --compact --filter=AuditLog
vendor/bin/sail artisan test --compact --filter=FindingWorkflow
vendor/bin/sail artisan test --compact --filter=WorkspaceMembership
vendor/bin/sail artisan test --compact --filter=SettingsWriter
vendor/bin/sail artisan test --compact --filter=RestoreRun
vendor/bin/sail artisan test --compact --filter=Baseline
vendor/bin/sail bin pint --dirty --format agent
```

## Expected outcome

- `/admin/audit-log` becomes a real canonical Monitoring page with meaningful filtering and event inspection.
- Audit events consistently capture actor, action, target, scope, timestamp, outcome, and safe structured context.
- Existing tenant and workspace audit writes converge on one shared recorder and one stable taxonomy.
- Covered governance and operational workflows emit readable audit entries without requiring raw JSON or source-record survival to understand what happened.
- Audit history is treated as durable evidence rather than short-lived tenant noise.