TenantAtlas/specs/136-admin-canonical-tenant/research.md

Research: Spec 136 Admin Panel Canonical Tenant Resolution Full Rollout

Decision 1: Use admin registration plus reachability to freeze the rollout manifest

Decision: Treat admin panel provider registration and direct admin page registration as the primary source of truth for admin-visible surfaces, but keep shared resources in scope when admin paths, deep links, embedded widgets, or dual-panel discovery can still execute their code in admin context.

Rationale:

• The codebase already exposes some resources directly in AdminPanelProvider, while others are tenant-scoped but still referenced from admin pages or shared navigation helpers.
• The spec cares about admin tenant drift, not only sidebar registration.
• Using reachability avoids missing shared resources that can still execute admin-path logic without appearing in admin navigation.

Alternatives considered:

• Limit the rollout strictly to resources registered in AdminPanelProvider: rejected because shared resources and pages can still create admin-path drift through direct URLs, deep links, or widgets.
• Treat every tenant resource as automatically in scope: rejected because some tenant-only surfaces have no admin-path behavior to harden.

Decision 2: Keep OperateHubShell as the canonical admin resolver

Decision: Continue using OperateHubShell::activeEntitledTenant(Request $request): ?Tenant as the only canonical tenant resolver for workspace-admin tenant-sensitive behavior.

Rationale:

• The support layer already encodes the intended admin priority order and entitlement checks.
• Spec 135 established this as the correct canonical pattern.
• A second public resolver would reintroduce the same drift risk under a new name.

Alternatives considered:

• Introduce a new universal resolver service: rejected because the feature must preserve the admin-versus-tenant-panel distinction.
• Resolve tenant state separately in each resource or page: rejected because the defect class is inconsistent surface-level resolution.

Decision 3: Persisted tenant-filter synchronization should standardize on CanonicalAdminTenantFilterState

Decision: Apply CanonicalAdminTenantFilterState::sync() as the standard synchronization primitive for admin surfaces that persist tenant-related filters in session.

Rationale:

• The helper already exists and clears or reseeds persisted tenant filter state based on the current canonical admin tenant.
• Filament v5 explicitly supports persistFiltersInSession(), so session-backed filter drift must be handled deliberately.
• AlertDeliveryResource and AuditLog already show the intended pattern.

Alternatives considered:

• Disable filter persistence on affected surfaces: rejected because persistence is an existing UX choice outside this feature.
• Hand-roll per-page session fixes: rejected because inconsistent local fixes are exactly what the rollout is trying to eliminate.

Decision 4: Search parity should reuse the admin-aware global-search trait or fall back to disablement

Decision: Reuse ScopesGlobalSearchToTenant for rollout resources that stay globally searchable in admin context, and disable admin-path search when parity cannot be guaranteed cheaply.

Rationale:

• Filament v5 requires a View or Edit page for global-searchable resources.
• The existing trait already distinguishes admin-panel and tenant-panel behavior by using OperateHubShell in the admin panel and Filament::getTenant() elsewhere.
• The constitution requires non-member-safe, tenant-safe global search.

Alternatives considered:

• Leave search behavior implicit: rejected because search can bypass list-level scoping and create the same drift bug.
• Build a separate search-only resolver: rejected because the existing trait already captures the right panel split.

Decision 5: Use AlertDeliveryResource and AuditLog as Type B reference patterns

Decision: Treat AlertDeliveryResource and AuditLog as the reference patterns for workspace-wide datasets with canonical tenant-default behavior.

Rationale:

• Both surfaces already combine workspace-wide data with synchronized tenant-default or tenant-filter behavior.
• Both already use OperateHubShell and CanonicalAdminTenantFilterState rather than raw panel-native tenant reads.
• They are good comparison points for ProviderConnectionResource, AuditLog guard expansion, and any EntraGroupResource workspace-wide follow-up behavior.

Alternatives considered:

• Use a pure tenant-scoped resource as the reference pattern: rejected because Type B surfaces have different requirements from Type A surfaces.
• Build a new shared reference helper first: rejected because the current reference patterns already exist in production code.

Decision 6: Treat Inventory page and widget alignment as one rollout slice

Decision: Handle InventoryCoverage and InventoryKpiHeader together so the page shell and embedded KPI widget use the same tenant rule.

Rationale:

• The spec names InventoryKpiHeader as an explicit correction case.
• Widget drift is one of the exact defect classes the feature is intended to eliminate.
• Page-level tenant context is not trustworthy unless the widget and its linked drill-down behavior follow the same source.

Alternatives considered:

• Fix the page only: rejected because widget-only drift would remain.
• Leave the widget workspace-wide while the page is tenant-sensitive: rejected because it violates one-surface, one-source semantics.

Decision 7: Shared tenant resources require panel-aware hardening even when admin navigation is absent

Decision: Keep shared tenant-sensitive resources such as RestoreRunResource, BackupSetResource, and other rollout targets in scope where their code can still be executed by admin paths, deep links, or shared helper logic, even if they do not register admin navigation.

Rationale:

• The spec explicitly calls out panel-safe behavior and shared-code review.
• Some resources are tenant-scoped in navigation yet still participate in admin-driven links, comparisons, or operational workflows.
• Drift can still occur inside shared methods, action URLs, and record-resolution logic.

Alternatives considered:

• Exclude tenant-routed resources from the rollout entirely: rejected because shared code can still carry unsafe resolver assumptions.
• Force admin registration for all tenant resources: rejected because the feature is about semantics, not information architecture redesign.

Decision 8: Surface classification should be explicit and operational

Decision: Freeze the rollout using three operational classes:

• Type A hard tenant-sensitive: PolicyResource, BackupScheduleResource, BackupSetResource, FindingResource, BaselineCompareLanding, RestoreRunResource, InventoryItemResource, PolicyVersionResource, TenantDiagnostics, InventoryCoverage, InventoryKpiHeader
• Type B workspace-wide with tenant-default: ProviderConnectionResource, AuditLog, EntraGroupResource follow-up when admin path remains workspace-wide with tenant-default semantics
• Type C workspace-only: AlertRuleResource, BaselineProfileResource, BaselineSnapshotResource, TenantResource, and other workspace-owned admin surfaces with no tenant-sensitive execution path

Rationale:

• The rollout needs a stable manifest for guard coverage and test scope.
• The classes match the behavior contract described in the spec.
• Explicit classification prevents accidental over-scoping of workspace-wide surfaces.

Alternatives considered:

• Keep an informal list only: rejected because guard and task generation need explicit categories.
• Add a fourth ambiguous class: rejected because the spec requires ambiguous surfaces to be resolved before implementation.

Decision 9: The guardrail should stay as a focused Pest architecture test

Decision: Expand AdminTenantResolverGuardTest rather than creating a new lint rule or analysis tool.

Rationale:

• The existing guard already scans selected canonical admin files for forbidden raw panel-native tenant reads.
• Pest is already the repo standard for architecture and regression guards.
• A focused allowlist and exception inventory is simpler to maintain than new tooling.

Alternatives considered:

• Add a PHPStan or ESLint-style custom rule: rejected because it is heavier than the feature requires.
• Rely on code review only: rejected because the feature explicitly asks for regression resistance and CI enforcement.

Decision 10: No asset or panel bootstrap changes are needed

Decision: Keep the rollout entirely inside existing Filament resources, pages, widgets, support helpers, and tests with no new assets or panel-provider wiring changes.

Rationale:

• The defect is semantic and behavioral, not presentational.
• Existing admin and tenant panels already provide the right routing and discovery model.
• Avoiding asset and provider changes minimizes regression risk and keeps deployment unchanged.

Alternatives considered:

• Add panel-specific assets or hooks to manage tenant state in the browser: rejected because the canonical source is server-side and already exists.
• Change panel registration or routing: rejected because the feature explicitly excludes panel redesign.