TenantAtlas/apps/platform/app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php
ahmido bef9020159 feat: implement spec 193 monitoring action hierarchy (#227)
## Summary
- codify Spec 193 as an explicit monitoring/workbench surface inventory with validator and guard coverage
- refactor the Finding Exceptions Queue, Operations landing, and tenantless operation viewer into clearer context, navigation, utility, drilldown, and focused-work lanes
- align Alerts, Audit Log, and Alert Deliveries with quiet origin-context handling while preserving calm reference surfaces and the explicit Tenant Diagnostics exception
- add focused feature coverage, guard coverage, browser smoke coverage, and the full spec artifacts for Spec 193

## Verification
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php tests/Feature/Guards/ActionSurfaceValidatorTest.php tests/Feature/Guards/Spec193MonitoringSurfaceHierarchyGuardTest.php tests/Feature/OpsUx/OperateHubShellTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php tests/Feature/Monitoring/FindingExceptionsQueueHierarchyTest.php tests/Browser/Spec193MonitoringSurfaceHierarchySmokeTest.php`
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- integrated-browser smoke pass over queue, operations, operation detail, alerts, audit log, and tenant diagnostics

## Notes
- Livewire v4 / Filament v5 stack unchanged
- no provider-registration changes; Laravel 11+ provider registration remains in `bootstrap/providers.php`
- no new global-search behavior was introduced
- destructive and governance-changing actions keep their existing confirmation and authorization semantics
- no new assets or migrations were added

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #227
2026-04-12 10:48:00 +00:00

545 lines
24 KiB
PHP

<?php
declare(strict_types=1);
namespace App\Support\Ui\ActionSurface;
use App\Filament\Pages\BaselineCompareLanding;
use App\Filament\Pages\BaselineCompareMatrix;
use App\Filament\Pages\Monitoring\Alerts;
use App\Filament\Pages\Monitoring\AuditLog;
use App\Filament\Pages\Monitoring\EvidenceOverview;
use App\Filament\Pages\Monitoring\FindingExceptionsQueue;
use App\Filament\Pages\Monitoring\Operations;
use App\Filament\Pages\Operations\TenantlessOperationRunViewer;
use App\Filament\Pages\Reviews\ReviewRegister;
use App\Filament\Pages\TenantDiagnostics;
use App\Filament\Resources\AlertDeliveryResource\Pages\ListAlertDeliveries;
use App\Filament\Resources\AlertDestinationResource\Pages\ViewAlertDestination;
use App\Filament\Resources\BackupSetResource\Pages\ViewBackupSet;
use App\Filament\Resources\BaselineProfileResource\Pages\ViewBaselineProfile;
use App\Filament\Resources\BaselineSnapshotResource\Pages\ViewBaselineSnapshot;
use App\Filament\Resources\EvidenceSnapshotResource\Pages\ViewEvidenceSnapshot;
use App\Filament\Resources\FindingExceptionResource\Pages\ViewFindingException;
use App\Filament\Resources\FindingResource\Pages\ViewFinding;
use App\Filament\Resources\PolicyVersionResource\Pages\ViewPolicyVersion;
use App\Filament\Resources\ProviderConnectionResource\Pages\ViewProviderConnection;
use App\Filament\Resources\ReviewPackResource\Pages\ViewReviewPack;
use App\Filament\Resources\TenantResource\Pages\EditTenant;
use App\Filament\Resources\TenantResource\Pages\ViewTenant;
use App\Filament\Resources\TenantReviewResource\Pages\ViewTenantReview;
use App\Filament\Resources\Workspaces\Pages\ViewWorkspace;
use App\Support\WorkspaceIsolation\TenantOwnedModelFamilies;
final class ActionSurfaceExemptions
{
/**
* @param array<string, string> $componentReasons
*/
public function __construct(
private readonly array $componentReasons,
) {}
public static function baseline(): self
{
return new self(array_merge([
// Baseline allowlist for legacy surfaces. Keep shrinking this list.
// Declared system table pages are discovered directly; deferred system tooling stays out of scope by not opting in.
'App\\Filament\\Pages\\Auth\\Login' => 'Auth entry page is out-of-scope for action-surface retrofits in spec 082.',
'App\\Filament\\Pages\\BreakGlassRecovery' => 'Break-glass flow is governed by dedicated security specs and tests.',
'App\\Filament\\Pages\\ChooseTenant' => 'Tenant chooser has no contract-style table action surface.',
'App\\Filament\\Pages\\ChooseWorkspace' => 'Workspace chooser has no contract-style table action surface.',
'App\\Filament\\Pages\\Tenancy\\RegisterTenant' => 'Tenant onboarding route is covered by onboarding/RBAC specs.',
'App\\Filament\\Pages\\TenantDashboard' => 'Dashboard retrofit deferred; widget and summary surfaces are excluded from this contract.',
'App\\Filament\\Pages\\Workspaces\\ManagedTenantOnboardingWizard' => 'Onboarding wizard has dedicated conformance tests in spec 172 (OnboardingVerificationTest, OnboardingVerificationClustersTest, OnboardingVerificationV1_5UxTest) and remains exempt from blanket discovery.',
'App\\Filament\\Pages\\Workspaces\\ManagedTenantsLanding' => 'Managed-tenant landing retrofit deferred to workspace feature track.',
], TenantOwnedModelFamilies::actionSurfaceBaselineExemptions()));
}
/**
* @return array<string, string>
*/
public function all(): array
{
return $this->componentReasons;
}
public function reasonForClass(string $className): ?string
{
return $this->componentReasons[$className] ?? null;
}
public function hasClass(string $className): bool
{
return array_key_exists($className, $this->componentReasons);
}
/**
* @return array<string, array{
* surfaceKey: string,
* classification: string,
* canonicalNoun: string,
* panelScope: string,
* ownerScope: string,
* routeKind: string,
* requiresHeaderRemediation: bool,
* exceptionReason: ?string,
* maxVisiblePrimaryActions: int,
* allowsNoPrimaryAction: bool,
* requiresGroupedSecondaryActions: bool,
* requiresDangerSeparation: bool,
* allowsPrimaryNavigation: bool,
* browserSmokeRequired: bool
* }>
*/
public static function spec192RecordPageInventory(): array
{
return [
ViewBaselineProfile::class => [
'surfaceKey' => 'baseline_profile_view',
'classification' => 'remediation_required',
'canonicalNoun' => 'Baseline profile',
'panelScope' => 'admin',
'ownerScope' => 'workspace-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => true,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => false,
'requiresGroupedSecondaryActions' => true,
'requiresDangerSeparation' => false,
'allowsPrimaryNavigation' => false,
'browserSmokeRequired' => true,
],
ViewEvidenceSnapshot::class => [
'surfaceKey' => 'evidence_snapshot_view',
'classification' => 'remediation_required',
'canonicalNoun' => 'Evidence snapshot',
'panelScope' => 'tenant',
'ownerScope' => 'tenant-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => true,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => false,
'requiresGroupedSecondaryActions' => false,
'requiresDangerSeparation' => true,
'allowsPrimaryNavigation' => false,
'browserSmokeRequired' => true,
],
ViewFindingException::class => [
'surfaceKey' => 'finding_exception_view',
'classification' => 'remediation_required',
'canonicalNoun' => 'Finding exception',
'panelScope' => 'tenant',
'ownerScope' => 'tenant-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => true,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => false,
'requiresDangerSeparation' => true,
'allowsPrimaryNavigation' => false,
'browserSmokeRequired' => true,
],
ViewTenantReview::class => [
'surfaceKey' => 'tenant_review_view',
'classification' => 'remediation_required',
'canonicalNoun' => 'Tenant review',
'panelScope' => 'tenant',
'ownerScope' => 'tenant-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => true,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => false,
'requiresGroupedSecondaryActions' => true,
'requiresDangerSeparation' => true,
'allowsPrimaryNavigation' => false,
'browserSmokeRequired' => true,
],
EditTenant::class => [
'surfaceKey' => 'tenant_edit',
'classification' => 'remediation_required',
'canonicalNoun' => 'Tenant',
'panelScope' => 'admin',
'ownerScope' => 'tenant-owned',
'routeKind' => 'edit',
'requiresHeaderRemediation' => true,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => true,
'requiresDangerSeparation' => true,
'allowsPrimaryNavigation' => false,
'browserSmokeRequired' => true,
],
ViewTenant::class => [
'surfaceKey' => 'tenant_view',
'classification' => 'workflow_heavy_special_type',
'canonicalNoun' => 'Tenant',
'panelScope' => 'admin',
'ownerScope' => 'tenant-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => false,
'exceptionReason' => 'Tenant detail remains a workflow-heavy hub for external links, verification/setup, and lifecycle operations. It may show one dominant next step, but it must never silently fall back to a flat multi-button strip.',
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => true,
'requiresDangerSeparation' => true,
'allowsPrimaryNavigation' => false,
'browserSmokeRequired' => true,
],
ViewProviderConnection::class => [
'surfaceKey' => 'provider_connection_view',
'classification' => 'minor_alignment_only',
'canonicalNoun' => 'Provider connection',
'panelScope' => 'admin',
'ownerScope' => 'tenant-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => false,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => true,
'requiresDangerSeparation' => true,
'allowsPrimaryNavigation' => true,
'browserSmokeRequired' => false,
],
ViewFinding::class => [
'surfaceKey' => 'finding_view',
'classification' => 'minor_alignment_only',
'canonicalNoun' => 'Finding',
'panelScope' => 'tenant',
'ownerScope' => 'tenant-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => false,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => true,
'requiresDangerSeparation' => true,
'allowsPrimaryNavigation' => true,
'browserSmokeRequired' => false,
],
ViewReviewPack::class => [
'surfaceKey' => 'review_pack_view',
'classification' => 'compliant_reference',
'canonicalNoun' => 'Review pack',
'panelScope' => 'tenant',
'ownerScope' => 'tenant-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => false,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => false,
'requiresDangerSeparation' => false,
'allowsPrimaryNavigation' => true,
'browserSmokeRequired' => true,
],
ViewAlertDestination::class => [
'surfaceKey' => 'alert_destination_view',
'classification' => 'compliant_reference',
'canonicalNoun' => 'Alert destination',
'panelScope' => 'admin',
'ownerScope' => 'workspace-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => false,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => false,
'requiresDangerSeparation' => false,
'allowsPrimaryNavigation' => true,
'browserSmokeRequired' => true,
],
ViewPolicyVersion::class => [
'surfaceKey' => 'policy_version_view',
'classification' => 'compliant_reference',
'canonicalNoun' => 'Policy version',
'panelScope' => 'admin',
'ownerScope' => 'workspace-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => false,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => false,
'requiresDangerSeparation' => false,
'allowsPrimaryNavigation' => true,
'browserSmokeRequired' => true,
],
ViewWorkspace::class => [
'surfaceKey' => 'workspace_view',
'classification' => 'compliant_reference',
'canonicalNoun' => 'Workspace',
'panelScope' => 'admin',
'ownerScope' => 'workspace-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => false,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => false,
'requiresDangerSeparation' => false,
'allowsPrimaryNavigation' => true,
'browserSmokeRequired' => true,
],
ViewBaselineSnapshot::class => [
'surfaceKey' => 'baseline_snapshot_view',
'classification' => 'compliant_reference',
'canonicalNoun' => 'Baseline snapshot',
'panelScope' => 'admin',
'ownerScope' => 'workspace-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => false,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => false,
'requiresDangerSeparation' => false,
'allowsPrimaryNavigation' => true,
'browserSmokeRequired' => true,
],
ViewBackupSet::class => [
'surfaceKey' => 'backup_set_view',
'classification' => 'compliant_reference',
'canonicalNoun' => 'Backup set',
'panelScope' => 'tenant',
'ownerScope' => 'tenant-owned',
'routeKind' => 'view',
'requiresHeaderRemediation' => false,
'exceptionReason' => null,
'maxVisiblePrimaryActions' => 1,
'allowsNoPrimaryAction' => true,
'requiresGroupedSecondaryActions' => true,
'requiresDangerSeparation' => true,
'allowsPrimaryNavigation' => true,
'browserSmokeRequired' => true,
],
];
}
/**
* @return array<string, array{
* surfaceKey: string,
* classification: string,
* canonicalNoun: string,
* panelScope: string,
* ownerScope: string,
* surfaceKind: string,
* primaryInspectModel: string,
* sharedPattern: string,
* requiresHeaderRemediation: bool,
* requiresExplicitDeclaration: bool,
* exceptionReason: ?string,
* browserSmokeRequired: bool
* }>
*/
public static function spec193MonitoringSurfaceInventory(): array
{
return [
FindingExceptionsQueue::class => [
'surfaceKey' => 'finding_exceptions_queue',
'classification' => 'remediation_required',
'canonicalNoun' => 'Finding exceptions',
'panelScope' => 'admin',
'ownerScope' => 'workspace-visible-tenant-owned',
'surfaceKind' => 'queue_workbench',
'primaryInspectModel' => 'explicit_inspect_action',
'sharedPattern' => 'operate_hub_shell',
'requiresHeaderRemediation' => true,
'requiresExplicitDeclaration' => true,
'exceptionReason' => null,
'browserSmokeRequired' => true,
],
TenantlessOperationRunViewer::class => [
'surfaceKey' => 'tenantless_operation_run_viewer',
'classification' => 'remediation_required',
'canonicalNoun' => 'Operation run',
'panelScope' => 'admin',
'ownerScope' => 'workspace-owned',
'surfaceKind' => 'monitoring_detail',
'primaryInspectModel' => 'singleton_detail_surface',
'sharedPattern' => 'operate_hub_shell',
'requiresHeaderRemediation' => true,
'requiresExplicitDeclaration' => true,
'exceptionReason' => null,
'browserSmokeRequired' => true,
],
Operations::class => [
'surfaceKey' => 'operations',
'classification' => 'remediation_required',
'canonicalNoun' => 'Operations',
'panelScope' => 'admin',
'ownerScope' => 'workspace-owned',
'surfaceKind' => 'monitoring_landing',
'primaryInspectModel' => 'clickable_row',
'sharedPattern' => 'operate_hub_shell',
'requiresHeaderRemediation' => true,
'requiresExplicitDeclaration' => true,
'exceptionReason' => null,
'browserSmokeRequired' => true,
],
Alerts::class => [
'surfaceKey' => 'alerts',
'classification' => 'minor_alignment_only',
'canonicalNoun' => 'Alerts',
'panelScope' => 'admin',
'ownerScope' => 'workspace-owned',
'surfaceKind' => 'monitoring_landing',
'primaryInspectModel' => 'page_level_overview',
'sharedPattern' => 'cluster_entry',
'requiresHeaderRemediation' => false,
'requiresExplicitDeclaration' => true,
'exceptionReason' => null,
'browserSmokeRequired' => false,
],
AuditLog::class => [
'surfaceKey' => 'audit_log',
'classification' => 'minor_alignment_only',
'canonicalNoun' => 'Audit log',
'panelScope' => 'admin',
'ownerScope' => 'workspace-visible-tenant-owned',
'surfaceKind' => 'read_only_report',
'primaryInspectModel' => 'explicit_inspect_action',
'sharedPattern' => 'operate_hub_shell',
'requiresHeaderRemediation' => false,
'requiresExplicitDeclaration' => true,
'exceptionReason' => null,
'browserSmokeRequired' => false,
],
ListAlertDeliveries::class => [
'surfaceKey' => 'alert_deliveries',
'classification' => 'minor_alignment_only',
'canonicalNoun' => 'Alert deliveries',
'panelScope' => 'admin',
'ownerScope' => 'workspace-owned',
'surfaceKind' => 'read_only_report',
'primaryInspectModel' => 'clickable_row',
'sharedPattern' => 'operate_hub_shell',
'requiresHeaderRemediation' => false,
'requiresExplicitDeclaration' => false,
'exceptionReason' => null,
'browserSmokeRequired' => false,
],
EvidenceOverview::class => [
'surfaceKey' => 'evidence_overview',
'classification' => 'compliant_no_op',
'canonicalNoun' => 'Evidence overview',
'panelScope' => 'admin',
'ownerScope' => 'workspace-visible-tenant-owned',
'surfaceKind' => 'read_only_report',
'primaryInspectModel' => 'clickable_row',
'sharedPattern' => 'none',
'requiresHeaderRemediation' => false,
'requiresExplicitDeclaration' => true,
'exceptionReason' => null,
'browserSmokeRequired' => true,
],
BaselineCompareLanding::class => [
'surfaceKey' => 'baseline_compare_landing',
'classification' => 'compliant_no_op',
'canonicalNoun' => 'Baseline compare',
'panelScope' => 'tenant',
'ownerScope' => 'tenant-owned',
'surfaceKind' => 'monitoring_landing',
'primaryInspectModel' => 'page_level_overview',
'sharedPattern' => 'none',
'requiresHeaderRemediation' => false,
'requiresExplicitDeclaration' => true,
'exceptionReason' => null,
'browserSmokeRequired' => true,
],
BaselineCompareMatrix::class => [
'surfaceKey' => 'baseline_compare_matrix',
'classification' => 'compliant_no_op',
'canonicalNoun' => 'Baseline compare matrix',
'panelScope' => 'tenant',
'ownerScope' => 'tenant-owned',
'surfaceKind' => 'read_only_report',
'primaryInspectModel' => 'matrix_itself',
'sharedPattern' => 'none',
'requiresHeaderRemediation' => false,
'requiresExplicitDeclaration' => true,
'exceptionReason' => null,
'browserSmokeRequired' => true,
],
ReviewRegister::class => [
'surfaceKey' => 'review_register',
'classification' => 'compliant_no_op',
'canonicalNoun' => 'Review register',
'panelScope' => 'admin',
'ownerScope' => 'workspace-visible-tenant-owned',
'surfaceKind' => 'read_only_report',
'primaryInspectModel' => 'clickable_row',
'sharedPattern' => 'none',
'requiresHeaderRemediation' => false,
'requiresExplicitDeclaration' => true,
'exceptionReason' => null,
'browserSmokeRequired' => true,
],
TenantDiagnostics::class => [
'surfaceKey' => 'tenant_diagnostics',
'classification' => 'special_type_acceptable',
'canonicalNoun' => 'Tenant diagnostics',
'panelScope' => 'tenant',
'ownerScope' => 'tenant-owned',
'surfaceKind' => 'diagnostic_exception',
'primaryInspectModel' => 'singleton_detail_surface',
'sharedPattern' => 'none',
'requiresHeaderRemediation' => false,
'requiresExplicitDeclaration' => true,
'exceptionReason' => 'Tenant diagnostics is already the focused diagnostic surface for the active tenant and may expose repair actions only when a real defect exists.',
'browserSmokeRequired' => true,
],
];
}
/**
* @return array{
* surfaceKey: string,
* classification: string,
* canonicalNoun: string,
* panelScope: string,
* ownerScope: string,
* routeKind: string,
* requiresHeaderRemediation: bool,
* exceptionReason: ?string,
* maxVisiblePrimaryActions: int,
* allowsNoPrimaryAction: bool,
* requiresGroupedSecondaryActions: bool,
* requiresDangerSeparation: bool,
* allowsPrimaryNavigation: bool,
* browserSmokeRequired: bool
* }|null
*/
public static function spec192RecordPageSurface(string $className): ?array
{
return self::spec192RecordPageInventory()[$className] ?? null;
}
/**
* @return array{
* surfaceKey: string,
* classification: string,
* canonicalNoun: string,
* panelScope: string,
* ownerScope: string,
* surfaceKind: string,
* primaryInspectModel: string,
* sharedPattern: string,
* requiresHeaderRemediation: bool,
* requiresExplicitDeclaration: bool,
* exceptionReason: ?string,
* browserSmokeRequired: bool
* }|null
*/
public static function spec193MonitoringSurface(string $className): ?array
{
return self::spec193MonitoringSurfaceInventory()[$className] ?? null;
}
}