TenantAtlas/specs/134-audit-log-foundation/quickstart.md

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
• 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
• app/Services/Intune/AuditLogger.php
• app/Services/Audit/WorkspaceAuditLogger.php
• app/Support/Audit/AuditActionId.php
• app/Support/Audit/AuditContextSanitizer.php
• app/Filament/Pages/Monitoring/AuditLog.php
• resources/views/filament/pages/monitoring/audit-log.blade.php
• app/Filament/Resources/OperationRunResource.php
• app/Filament/Resources/AlertDeliveryResource.php
• app/Services/Findings/FindingWorkflowService.php
• app/Services/Auth/WorkspaceMembershipManager.php
• app/Services/Settings/SettingsWriter.php
• app/Console/Commands/TenantpilotPurgeNonPersistentData.php

Suggested validation commands

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.