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

# Research: Spec 135 Canonical Tenant Context Resolution

## Decision 1: Preserve explicit split semantics between panels

**Decision**: Keep tenant-panel and workspace-admin tenant resolution as two explicit concepts. Tenant-panel flows continue to use panel-native tenant context. Workspace-admin flows continue to use `OperateHubShell::activeEntitledTenant(Request $request): ?Tenant`.

**Rationale**:
- The spec explicitly forbids an unspecified universal resolver.
- Existing code already encodes the correct admin behavior in `OperateHubShell`.
- Tenant-panel screens legitimately use `Filament::getTenant()` and `Tenant::current()` because the tenant is part of panel-native routing semantics.

**Alternatives considered**:
- Build a single app-wide tenant resolver service: rejected because it would blur the admin-versus-tenant distinction the spec wants to preserve.
- Convert all existing tenant reads to admin semantics: rejected because tenant-panel pages are intentionally panel-native.

## Decision 2: Treat `OperateHubShell` as the canonical admin priority rule

**Decision**: Use `OperateHubShell::activeEntitledTenant(Request $request): ?Tenant` as the single admin source of truth and document its priority order as:
1. entitled Filament tenant,
2. entitled remembered workspace tenant,
3. null when neither is valid.

**Rationale**:
- `OperateHubShell` already resolves the conflict the spec describes.
- It already checks entitlement before returning a tenant.
- It already drives visible admin UI labels such as “Filtered by tenant” and tenant return affordances.

**Alternatives considered**:
- Resolve directly from session in each page/resource: rejected because the bug class is inconsistent per-surface resolution.
- Prefer remembered tenant over Filament tenant: rejected because existing admin code and the spec’s conflict scenario require Filament tenant to win.

## Decision 3: Use alert delivery as the admin reference pattern

**Decision**: Use `AlertDeliveryResource` as the “already correct” admin reference pattern for query scoping, tenant filter defaults, and tenant filter option narrowing.

**Rationale**:
- The resource already scopes by workspace and tenant entitlement.
- It already uses `OperateHubShell::activeEntitledTenant()` for both query narrowing and filter default behavior.
- Its record URL and read-only list structure already fit the feature’s target class of admin monitoring flows.

**Alternatives considered**:
- Use Operations as the reference pattern: rejected because Operations is one of the surfaces that still has an inconsistency in its KPI widget.
- Use a tenant-panel resource as reference: rejected because the feature is specifically about admin-panel canonical behavior.

## Decision 4: Treat Operations page and KPI widget as one remediation unit

**Decision**: Plan the Operations page shell and `OperationsKpiHeader` widget as one remediation slice.

**Rationale**:
- `Monitoring\Operations` already uses `OperateHubShell` for header actions and table query narrowing.
- `OperationsKpiHeader` still reads `Filament::getTenant()` directly, which can disagree with the page header and table when only remembered tenant context exists.
- The spec requires visible tenant context, counts, widgets, filters, and links to resolve from the same canonical tenant.

**Alternatives considered**:
- Fix only the page query: rejected because the current inconsistency class is specifically page shell versus widget mismatch.
- Leave the widget workspace-wide while the table is tenant-scoped: rejected because that violates visible-scope parity.

## Decision 5: Harden OperationRun filters against stale persisted state

**Decision**: Revalidate tenant-sensitive persisted filters against the current canonical admin tenant on every relevant request.

**Rationale**:
- `OperationRunResource` persists filters in session.
- The tenant filter default already uses `OperateHubShell`, but some other filter option builders still reference raw `Filament::getTenant()`.
- The spec explicitly calls out persisted tenant-sensitive filter state as a regression risk when switching tenants.

**Alternatives considered**:
- Disable filter persistence entirely: rejected because persistence is a broader UX choice outside this feature.
- Trust the persisted filter if it still parses: rejected because syntactic validity is not the same as tenant-scope validity.

## Decision 6: Entra groups need record-resolution hardening, not just table scoping

**Decision**: Treat Entra groups as a list-plus-record-resolution problem. Scope must be aligned in `table()`, `getEloquentQuery()`, direct record/view access, and global search.

**Rationale**:
- `EntraGroupResource::table()` narrows using `Tenant::current()`.
- `EntraGroupResource::getEloquentQuery()` currently returns the broader base query.
- The resource has a view page, so direct record URLs can bypass table-only constraints.
- The spec explicitly names Entra group record-resolution and search as in-scope remediation.

**Alternatives considered**:
- Scope only the table query: rejected because the feature exists to fix list/detail/search parity.
- Remove the view page: rejected because the spec focuses on safe access, not reducing product capability.

## Decision 7: Use a panel-aware search rule or disable admin global search for Entra groups

**Decision**: Prefer a panel-aware scoped global-search query for Entra groups. If implementation cannot guarantee parity cheaply, disable global search for that resource in admin contexts.

**Rationale**:
- The constitution and spec both require tenant-safe, non-member-safe search behavior.
- The repo already has a tenant-scoped search concern based on `Filament::getTenant()`, but that is not sufficient for admin remembered-tenant semantics.
- The spec allows disabling global search where safe parity cannot be guaranteed.

**Alternatives considered**:
- Leave current search behavior implicit: rejected because the spec explicitly calls out search entry points.
- Build a broad search-only exception: rejected because it would reintroduce scope drift.

## Decision 8: The guardrail should be a focused architecture test, not a new lint tool

**Decision**: Implement the lightweight guardrail as a Pest architecture/regression test that scans selected admin Filament paths for raw `Filament::getTenant()` and `Tenant::current()` patterns, with a documented allowlist for tenant-panel-native files.

**Rationale**:
- The repo already relies on Pest for regression guards.
- This keeps the feature self-contained and avoids adding external tooling.
- The test can fail with actionable file paths and still permit explicit documented exceptions.

**Alternatives considered**:
- Add a custom PHPStan rule or external linter: rejected because it is heavier than the spec requires.
- Rely on code review discipline only: rejected because the feature explicitly asks for a maintainable guardrail.