TenantAtlas/specs/186-tenant-registry-recovery-triage/plan.md

# Implementation Plan: Tenant Registry Recovery Triage

**Branch**: `186-tenant-registry-recovery-triage` | **Date**: 2026-04-09 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/186-tenant-registry-recovery-triage/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/186-tenant-registry-recovery-triage/spec.md`

## Summary

Turn the existing tenant registry into the operator’s portfolio recovery-triage surface without creating a second recovery-truth system. The implementation will keep `TenantBackupHealthResolver` and `RestoreSafetyResolver` as the only truth sources for tenant backup posture and tenant recovery evidence, project those states onto `TenantResource` as bounded list columns, add exact posture filters and deterministic worst-first ordering, and change workspace backup and recovery multi-tenant drilldowns from `ChooseTenant` to the filtered tenant registry while preserving single-tenant direct-to-dashboard behavior. The slice stays read-only, introduces no schema change, no new persistence, no new resolver truth, no new panel or asset registration, and no broader dashboard or chooser redesign.

Key approach: work inside the existing `TenantResource`, `ListTenants`, `WorkspaceOverviewBuilder`, and workspace widget seams; batch-load posture state via `assessMany()` and `dashboardRecoveryEvidenceForTenants()` across the current visible workspace tenant set; preserve intent through exact query-string filter parameters on `/admin/tenants`; keep the Filament list action-surface contract intact; and validate the result with focused Pest, Livewire, truthfulness, and RBAC coverage.

## Technical Context

**Language/Version**: PHP 8.4, Laravel 12, Blade, Filament v5, Livewire v4  
**Primary Dependencies**: Filament v5 resources and table filters, Livewire v4 `ListRecords`, Pest v4, Laravel Sail, existing `TenantResource`, `ListTenants`, `WorkspaceOverviewBuilder`, `TenantBackupHealthResolver`, `TenantBackupHealthAssessment`, `RestoreSafetyResolver`, `RecoveryReadiness`, and shared badge infrastructure  
**Storage**: PostgreSQL with existing tenant-owned `tenants`, `backup_sets`, `backup_items`, `restore_runs`, `policies`, and membership records; no schema change planned  
**Testing**: Pest feature tests, Livewire resource-page tests, and focused unit coverage only if a narrow shared presentation or ranking seam is extracted, all run through Sail  
**Target Platform**: Laravel web application in Sail locally and containerized Linux deployment in staging and production
**Project Type**: Laravel monolith web application rooted at `apps/platform`  
**Performance Goals**: Keep registry rendering DB-only and query-bounded, avoid per-row resolver N+1 behavior, preserve current table pagination and session-persisted filter or sort behavior, and keep the operator’s first-scan triage answer within 5 to 10 seconds  
**Constraints**: No new persisted portfolio posture table, no new recovery score, no chooser redesign, no tenant-level resolver truth change, no cross-tenant leakage, no new dashboard widgets, no extra registry inspect action, no page-local badge language, and no new Filament assets  
**Scale/Scope**: One workspace overview builder, one tenant registry resource and page pair, one existing workspace summary or attention destination contract, optional shared badge or copy extension for existing posture states, and focused regression coverage across filters, ordering, drilldowns, truthfulness, and RBAC

## Constitution Check

*GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.*

| Principle | Status | Notes |
|-----------|--------|-------|
| Inventory-first | Pass | The feature reads existing tenant backup and restore evidence only; no new source of truth or snapshot behavior is introduced |
| Read/write separation | Pass | This is a read-first list and drilldown hardening slice with no new write path |
| Graph contract path | Pass | No Microsoft Graph call or `config/graph_contracts.php` change is required |
| Deterministic capabilities | Pass | Existing capability registry and current tenant or workspace scope rules remain authoritative |
| RBAC-UX planes and 404 vs 403 | Pass | Workspace surfaces stay under `/admin`, tenant follow-up stays under `/admin/t/{tenant}`, non-members remain `404`, and deeper capability checks remain server-side |
| Workspace isolation | Pass | Only current-workspace and in-scope tenants may appear in the registry or drilldowns |
| Tenant isolation | Pass | Registry posture is still derived per tenant and filtered to visible memberships only |
| Destructive confirmation standard | Pass | No new destructive action is introduced; existing destructive tenant actions remain unchanged and confirmed |
| Global search safety | Pass | TenantResource already has view and edit pages; this slice does not broaden global-search scope or semantics |
| Run observability | Pass | No new queued work, no new `OperationRun`, and no lifecycle transition is added |
| Ops-UX 3-surface feedback | Pass | No run feedback surface is added or changed |
| Ops-UX lifecycle ownership | Pass | `OperationRun.status` and `OperationRun.outcome` remain untouched |
| Ops-UX summary counts | Pass | No `summary_counts` change is needed |
| Data minimization | Pass | Registry posture uses existing derived summaries and does not expose deeper payload detail |
| Proportionality (PROP-001) | Pass | Changes stay inside existing list and builder seams; no new persistence, no new page shell, and no new portfolio framework |
| No premature abstraction (ABSTR-001) | Pass | The plan prefers local resource or page logic plus existing resolvers; any shared badge or copy extraction stays within already-existing seams |
| Persisted truth (PERSIST-001) | Pass | No new table, column, cache, or materialized posture mirror is introduced |
| Behavioral state (STATE-001) | Pass | Registry reuses existing posture states only; no new domain state family is added |
| UI semantics (UI-SEM-001) | Pass | The registry projects existing domain truth directly; no new explanation or confidence framework is introduced |
| Badge semantics (BADGE-001) | Pass | Status-like registry badges must use shared badge or copy semantics rather than ad-hoc local colors or labels |
| Filament-native UI (UI-FIL-001) | Pass | Existing Filament table columns, filters, and widgets remain the implementation seams |
| UI Action Surface Contract | Pass | `TenantResource` remains a list-first resource with row-click inspect and at most one inline safe shortcut; no redundant View action is added |
| Filament UX-001 | Pass with documented variance | No create or edit layout change is involved; this slice refines list scanability, filters, and drillthrough continuity only |
| Filament v5 / Livewire v4 compliance | Pass | The implementation stays inside the current Filament v5 and Livewire v4 stack |
| Provider registration location | Pass | No panel or provider change is required; Laravel 11+ provider registration remains in `bootstrap/providers.php` |
| Asset strategy | Pass | No new assets are planned; existing deployment `filament:assets` behavior remains unchanged |

## Phase 0 Research

Research outcomes are captured in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/186-tenant-registry-recovery-triage/research.md`.

Key decisions:

- Use workspace-scoped batch posture maps built from `TenantBackupHealthResolver::assessMany()` and `RestoreSafetyResolver::dashboardRecoveryEvidenceForTenants()` instead of per-row resolver calls or a persisted registry summary.
- Preserve workspace drilldown intent through exact `/admin/tenants` query parameters and `ListTenants` initialization rather than `ChooseTenant`, hidden session-only state, or a new page shell.
- Use multi-select posture filters so workspace backup attention can preselect `absent`, `stale`, and `degraded`, and workspace recovery attention can preselect `weakened` and `unvalidated`, without inventing a pseudo `needs attention` filter value.
- Keep the TenantResource action-surface contract intact: full-row click remains inspect, and the existing one-inline-shortcut pattern remains the fast next click.
- Reuse or extract one shared mapping seam from `RecoveryReadiness` for label, tone, and fallback-URL semantics so the registry and dashboard cannot drift into parallel local mapping tables for the same posture states.
- Extend the current workspace summary-metric tests, workspace continuity tests, tenant registry scope tests, and table-guard coverage rather than introducing a browser-first harness.

## Phase 1 Design

Design artifacts are created under `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/186-tenant-registry-recovery-triage/`:

- `research.md`: implementation and design decisions for posture loading, exact filter intent, and continuity behavior
- `data-model.md`: existing persisted inputs plus the derived registry row and triage-intent model
- `contracts/tenant-registry-recovery-triage.openapi.yaml`: internal route contract for filtered registry and single-tenant dashboard drilldowns
- `quickstart.md`: focused automated and manual validation workflow for registry posture triage

Design decisions:

- No schema migration is required. The registry will consume existing tenant truth and derive row-level posture and rank at render time.
- `TenantResource` remains workspace-scoped and continues to own the canonical `/admin/tenants` surface. The feature adds columns, filters, and triage ordering, not a new resource or a new shell.
- Triage filtering should be exact, not vague. Backup drilldowns preselect `absent`, `stale`, and `degraded`; recovery drilldowns preselect `weakened` and `unvalidated`; both default to worst-first sorting.
- Worst-first ordering must operate over the filtered visible tenant set before pagination, using a deterministic tier map and a stable secondary order.
- `WorkspaceOverviewBuilder` is the only place where backup and recovery multi-tenant drilldown destinations need to change. Existing workspace widgets already honor `destination_url` and should not need a new interaction model.
- The tenant dashboard remains the safe fallback next step whenever deeper backup or restore surfaces would lose the same posture reason or fail permission checks.

## Project Structure

### Documentation (this feature)

```text
specs/186-tenant-registry-recovery-triage/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── tenant-registry-recovery-triage.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md
```

### Source Code (repository root)

```text
apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   └── WorkspaceOverview.php
│   │   ├── Resources/
│   │   │   ├── TenantResource.php
│   │   │   └── TenantResource/
│   │   │       └── Pages/
│   │   │           └── ListTenants.php
│   │   └── Widgets/
│   │       ├── Dashboard/
│   │       │   └── RecoveryReadiness.php
│   │       └── Workspace/
│   │           ├── WorkspaceNeedsAttention.php
│   │           └── WorkspaceSummaryStats.php
│   └── Support/
│       ├── BackupHealth/
│       │   ├── TenantBackupHealthAssessment.php
│       │   └── TenantBackupHealthResolver.php
│       ├── RestoreSafety/
│       │   └── RestoreSafetyResolver.php
│       ├── Workspaces/
│       │   └── WorkspaceOverviewBuilder.php
│       └── Badges/
│           ├── BadgeCatalog.php
│           ├── BadgeDomain.php
│           └── BadgeRenderer.php
└── tests/
    ├── Feature/
    │   └── Filament/
    │       ├── TenantResourceIndexIsWorkspaceScopedTest.php
    │       ├── WorkspaceOverviewAuthorizationTest.php
    │       ├── WorkspaceOverviewDrilldownContinuityTest.php
    │       ├── WorkspaceOverviewSummaryMetricsTest.php
    │       └── TenantRegistryRecoveryTriageTest.php
    └── Feature/
        └── Guards/
            ├── ActionSurfaceContractTest.php
            └── FilamentTableStandardsGuardTest.php
```

**Structure Decision**: Standard Laravel monolith under `apps/platform`. The implementation stays inside the current tenant registry resource, current workspace overview builder, existing workspace widgets, and existing tests. If a shared presentation seam is required for the new registry badges, it must extend an existing badge or copy surface rather than introducing a new framework.

## Implementation Strategy

### Phase A — Build Workspace-Scoped Posture Snapshots For The Registry

**Goal**: Make backup posture, recovery evidence, filter sets, and triage rank available to the registry without per-row resolver calls or a new persisted summary.

| Step | File | Change |
|------|------|--------|
| A.1 | `apps/platform/app/Filament/Resources/TenantResource.php` | Add one request-scoped posture snapshot path over the already scoped tenant set using `assessMany()` and `dashboardRecoveryEvidenceForTenants()`, keyed by tenant ID and reusable by columns, filters, and worst-first ordering |
| A.2 | `apps/platform/app/Filament/Resources/TenantResource.php` | Derive exact filter buckets and triage rank buckets from the snapshot map so filtering and ordering operate on the same truth source |
| A.3 | `apps/platform/app/Filament/Widgets/Dashboard/RecoveryReadiness.php` and `apps/platform/app/Filament/Resources/TenantResource.php` | Reuse or extract one shared bounded label or tone mapping seam for `absent`, `stale`, `degraded`, `healthy`, `weakened`, `unvalidated`, and `no recent issues visible` rather than local page-only mappings |

### Phase B — Turn TenantResource Into A Working Triage Surface

**Goal**: Add visible posture truth, exact filters, and deterministic weak-first ordering while keeping the current list action surface stable.

| Step | File | Change |
|------|------|--------|
| B.1 | `apps/platform/app/Filament/Resources/TenantResource.php` | Add default-visible `Backup posture` and `Recovery evidence` columns near tenant identity and lifecycle, keeping metadata and recovery truth visually separate |
| B.2 | `apps/platform/app/Filament/Resources/TenantResource.php` | Add multi-select backup-posture and recovery-evidence filters using exact state values and workspace-scoped `whereIn` filtering over snapshot-derived tenant ID sets |
| B.3 | `apps/platform/app/Filament/Resources/TenantResource.php` | Add deterministic worst-first ordering using the triage-rank map and stable secondary ordering by tenant name while preserving current default calm browsing when triage ordering is not requested |
| B.4 | `apps/platform/app/Filament/Resources/TenantResource.php` | Keep row click as the canonical inspect model and reuse the existing safe inline shortcut for fast next-step clarity instead of adding a new View action |

### Phase C — Preserve Drilldown Intent On `/admin/tenants`

**Goal**: Ensure workspace backup and recovery drilldowns open the registry in a visibly filtered, weak-first state rather than losing cause in `ChooseTenant`.

| Step | File | Change |
|------|------|--------|
| C.1 | `apps/platform/app/Filament/Resources/TenantResource/Pages/ListTenants.php` | Add narrow query-string initialization for exact posture filter arrays and `triage_sort=worst_first`, translating them into the page’s table filter or sort state without changing the core page model |
| C.2 | `apps/platform/app/Filament/Resources/TenantResource/Pages/ListTenants.php` | Preserve existing session-backed list state while allowing explicit query-string intent to override it on first load for workspace drilldowns |
| C.3 | `apps/platform/app/Filament/Resources/TenantResource.php` and `ListTenants.php` | Add a bounded empty-state or subheading strategy for zero-match filtered triage views so the registry stays scoped and honest even when no visible tenant matches the current filter |

### Phase D — Change Workspace Backup And Recovery Multi-Tenant Destinations

**Goal**: Move multi-tenant backup and recovery attention drilldowns from `ChooseTenant` to the filtered registry while keeping exact single-tenant behavior.

| Step | File | Change |
|------|------|--------|
| D.1 | `apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php` | Replace multi-tenant `choose_tenant` destinations for `backup_attention_tenants` and `recovery_attention_tenants` with exact `/admin/tenants` URLs carrying posture filter arrays and `triage_sort=worst_first` |
| D.2 | `apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php` | Keep single-tenant backup or recovery drilldowns routed directly to the tenant dashboard when only one visible tenant is affected |
| D.3 | `apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php` and existing workspace widgets | Keep the existing `destination_url` and destination-kind contract unchanged and do not introduce a new `tenant_registry` kind label for this slice |

### Phase E — Lock Semantics With Focused Regression Coverage

**Goal**: Protect list truth, triage ordering, workspace continuity, and scope safety against regression.

| Step | File | Change |
|------|------|--------|
| E.1 | `apps/platform/tests/Feature/Filament/TenantRegistryRecoveryTriageTest.php` | Add focused coverage for row posture rendering, exact backup filters, exact recovery filters, worst-first ordering, overclaim avoidance, and metadata separation |
| E.2 | `apps/platform/tests/Feature/Filament/WorkspaceOverviewSummaryMetricsTest.php` | Update the backup-attention multi-tenant expectation from `choose_tenant` to the filtered tenant registry and add equivalent multi-tenant recovery coverage where needed |
| E.3 | `apps/platform/tests/Feature/Filament/WorkspaceOverviewDrilldownContinuityTest.php` | Extend continuity coverage so backup and recovery attention preserve meaning through the tenant-registry destination as well as single-tenant dashboard destinations |
| E.4 | `apps/platform/tests/Feature/Filament/WorkspaceOverviewAuthorizationTest.php` and `TenantResourceIndexIsWorkspaceScopedTest.php` | Verify no hidden-tenant leakage across posture filters, triage ordering, or workspace drilldowns |
| E.5 | `apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php` and `FilamentTableStandardsGuardTest.php` | Keep existing list-surface and table-standards guards passing after the registry column and filter changes |
| E.6 | `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` and focused Pest runs | Required formatting and targeted verification before implementation is considered complete |

## Key Design Decisions

### D-001 — Registry posture stays fully derived

The tenant registry consumes existing backup and recovery truth at render time. There is no new tenant summary table, no cached portfolio score, and no new recovery-confidence persistence.

### D-002 — Exact states beat vague attention flags

Workspace drilldowns should preselect exact posture states, not a generic `needs attention` filter. That keeps the registry honest and makes the visible filter state itself the explanation.

### D-003 — Weak-first ordering must happen before pagination

If ranking happens only on the current page, the worst tenant may remain hidden on another page. The rank map therefore needs to shape the filtered query order over the full scoped tenant set before pagination.

### D-004 — Existing list interaction model remains intact

`TenantResource` already satisfies the list-first inspect model. The feature must not turn it into a multi-action dashboard or add a redundant View affordance.

### D-005 — Recovery-readiness semantics should not fork

The codebase already has one place that renders backup posture and recovery evidence together: `RecoveryReadiness`. The registry should call the same shared bounded mapping seam, either by reusing existing methods or by extracting a narrow helper into the same seam, rather than creating another local mapping language inside `TenantResource`.

### D-006 — Workspace widgets keep the existing destination contract

The workspace widgets already consume `destination_url` correctly. This slice changes those URLs for multi-tenant backup and recovery drilldowns, but it does not add a new destination-kind value or require a widget interaction redesign.

### D-007 — Workspace overview only changes destination logic

The workspace overview already computes backup and recovery attention correctly. This slice changes where multi-tenant clicks land, not what those metrics mean.

## Risk Assessment

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Registry filtering or ranking is computed only for the current page and hides weaker tenants on later pages | High | Medium | Build filter buckets and triage rank across the full scoped tenant set before pagination and cover with ordering tests |
| Registry adds new local badge or tone mappings that drift from existing dashboard posture semantics | High | Medium | Reuse existing shared badge or copy seams and add truthfulness coverage for labels and tones |
| Multi-tenant workspace drilldowns still lose cause because filter intent is not visibly applied on first load | High | Medium | Initialize ListTenants from exact query parameters and cover continuity through summary-metric and drilldown tests |
| Metadata such as lifecycle status or last sync visually reads like recovery truth after the new columns are added | Medium | Medium | Place backup posture and recovery evidence explicitly, keep them separately labeled, and add no-metadata-substitution coverage |
| Batch posture loading over the scoped tenant set becomes too expensive in larger workspaces | Medium | Medium | Reuse existing batch resolvers, keep query shape bounded to the current scoped tenant set, and cover the feature with query-bounded regression expectations |

## Test Strategy

- Add a focused tenant-registry triage feature test as the primary acceptance harness for row rendering, filters, worst-first ordering, and truthfulness.
- Add explicit query-bounded regression coverage so registry posture loading does not degrade into uncontrolled per-row resolver fanout.
- Extend current workspace summary-metric and drilldown continuity tests so multi-tenant backup and recovery destinations move from `ChooseTenant` to the filtered registry without regressing the single-tenant dashboard path.
- Extend workspace authorization and tenant registry scope coverage so posture filters and registry drilldowns remain bounded to visible tenants only.
- Keep existing action-surface and table-standards guards green so the tenant registry stays compliant with the Filament list contract after the new columns and filters are added.
- Prefer Livewire or feature-level verification over browser-first testing because the codebase already has direct coverage seams for `ListTenants`, `WorkspaceOverviewBuilder`, and related widgets.
- Run all focused tests through Sail and finish with `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.