TenantAtlas/specs/135-canonical-tenant-context-resolution/quickstart.md

Quickstart: Spec 135 Canonical Tenant Context Resolution

Goal

Implement the canonical tenant-context rule for workspace-admin flows, preserve tenant-panel-native semantics, and leave the feature ready for direct test-driven implementation.

Expected implementation slices

1. Refine or document the admin resolver contract in the support layer.
2. Align the Operations monitoring shell and KPI widget to the same canonical admin tenant.
3. Revalidate OperationRun tenant-sensitive filter defaults, options, and persisted state.
4. Harden Entra group list, detail, and search behavior to the same scope contract.
5. Preserve alert delivery as the reference admin pattern.
6. Add the architecture guardrail and regression tests.

Recommended implementation order

1. Update the support-layer context contract and any small helper extraction first.
2. Fix Operations page plus KPI parity and extend existing monitoring tests.
3. Fix OperationRun filter option/default parity and stale persisted filter handling.
4. Fix Entra group query, record-resolution, and search behavior.
5. Add the guardrail test with explicit allowlist entries.
6. Run formatting and the minimal affected Pest suite.

Focused verification commands

Run all commands from the repository root.

vendor/bin/sail artisan test --compact \
  tests/Feature/Monitoring/OperationsKpiHeaderTenantContextTest.php \
  tests/Feature/Monitoring/OperationsTenantScopeTest.php \
  tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php \
  tests/Feature/Spec085/OperationsIndexHeaderTest.php \
  tests/Feature/Spec085/RunDetailBackAffordanceTest.php \
  tests/Feature/Filament/OperationRunListFiltersTest.php \
  tests/Feature/Filament/EntraGroupAdminScopeTest.php \
  tests/Feature/Filament/EntraGroupGlobalSearchScopeTest.php \
  tests/Feature/DirectoryGroups/BrowseGroupsTest.php \
  tests/Feature/Filament/EntraGroupEnterpriseDetailPageTest.php \
  tests/Feature/Filament/PolicyVersionResolvedReferenceLinksTest.php \
  tests/Feature/Filament/EntraGroupResolvedReferencePresentationTest.php \
  tests/Feature/Guards/AdminTenantResolverGuardTest.php \
  tests/Feature/OpsUx/OperateHubShellTest.php \
  tests/Feature/Filament/Alerts/AlertsKpiHeaderTest.php \
  tests/Feature/Alerts/AlertDeliveryDeepLinkFiltersTest.php
vendor/bin/sail artisan test --compact \
  tests/Feature/Filament/TableStatePersistenceTest.php \
  tests/Feature/Filament/TenantScopingTest.php \
  tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php \
  tests/Unit/Support/References/CapabilityAwareReferenceResolverTest.php
vendor/bin/sail bin pint --dirty --format agent

Scenario matrix to cover in tests

Admin monitoring flows

• remembered-only request resolves one tenant across header, KPIs, and table
• Filament-only request resolves one tenant across header, KPIs, and table
• conflicting request prefers Filament tenant everywhere
• no-context request renders the workspace-scoped All tenants state, clears tenant-default filters, and suppresses tenant-only KPI behavior

OperationRun filters and detail flows

• tenant filter defaults match canonical tenant
• tenant filter options never exceed current canonical tenant scope
• stale persisted filter state is reset, ignored, or replaced after tenant switch
• direct detail view does not reveal a broader record than the list would show
• no-context detail rendering is allowed only when the record still satisfies workspace scope and tenant entitlement; otherwise the response is not found

Entra groups

• list query matches canonical tenant scope
• direct record URL obeys the same tenant boundary as the list
• admin list and direct record requests without canonical tenant context return not found
• out-of-scope requests return not found
• admin global search returns no tenant-owned Entra-group results without canonical tenant context, or is explicitly disabled

Guardrail

• a new admin-only Filament::getTenant() or Tenant::current() read fails the architecture test
• approved tenant-panel-native files remain explicitly allowed

Out of scope during implementation

• broad tenancy refactors outside the inconsistency class named in the spec
• dependency additions
• unrelated tenant-panel resource rewrites for style only
• new user-facing flows outside the existing admin and tenant-panel surfaces