# Research: Filament v5.2.1 Upgrade

**Feature**: 102-filament-5-2-1-upgrade  
**Date**: 2026-02-20

## Upstream Notes (v5.2.0 → v5.2.1)

Source: Filament GitHub releases (`v5.2.0...v5.2.1`). Highlights relevant to this repo’s verification gates:

- Tenancy: **"Don't register tenancy on models when it is not active"**
  - Risk: Multi-panel apps may previously have had unintended tenant scoping or auto-association in a non-tenant panel.
  - Verification mapping: staging smoke must include both `/admin` and `/system` panels and check for unexpected tenant filtering or missing tenant association.

- Tables: **"bulk action receives non-selectable records when using \"Select all\""**
  - Risk: bulk actions can behave incorrectly when tables use non-selectable rows.
  - Verification mapping: smoke includes select-all + non-selectable-row scenarios.

- Testing: **"Fix assertHasTableActionErrors() deprecated replacement"**
  - Risk: tests relying on deprecated assertion guidance may need to follow the corrected replacement pattern.
  - Verification mapping: full suite must be green; treat any new deprecation warnings or assertion failures as regressions to address.

## Decisions

### Decision: Upgrade Filament constraint to `^5.2.1`

- Rationale:
  - Patch-level stability/bugfix upgrade with known fixes relevant to this app (tenancy registration behavior; table bulk selection; testing assertions).
  - Keeps us current within Filament v5 and reduces upgrade debt.
- Alternatives considered:
  - Stay on `^5.0` until a larger upgrade window is available (rejected: leaves known upstream fixes unconsumed).

### Decision: Allow plugin/extension dependency bumps (Composer-only) in the same PR

- Rationale:
  - Patch upgrades can be blocked by transitive constraints; allowing composer-only plugin bumps preserves the “dependency-only” scope.
  - Avoids splitting into multiple PRs that each touch `composer.lock` while still preventing application code changes.
- Alternatives considered:
  - Strict Filament-only bump; abort on plugin incompatibility (rejected: increases likelihood of blocking the upgrade).
  - Allow minimal application code compatibility fixes (rejected: conflicts with “no feature changes” scope).

### Decision: Verification gates

- Automated gate (required): **Full automated regression suite + frontend build**
  - Rationale: ensures both PHP/Livewire/Filament and frontend asset pipeline remain stable.
  - Alternatives considered: tests-only (rejected: build failures often surface asset regressions).

- Manual gate (required): **Staging UI smoke** for Admin (`/admin`) and System (`/system`, if present)
  - Rationale: catches runtime regressions that can slip past tests (modals, table selection, tenancy-related UI behavior).
  - Alternatives considered: local-only smoke (rejected: staging is closer to production and aligns with rollback criteria).

### Decision: Rollback strategy

- Rationale:
  - Fastest safe rollback is to revert `composer.lock` (and the Filament constraint if changed) and redeploy the last known-good artifact.
- Alternatives considered:
  - “Forward fix” under pressure (rejected: increases outage window and risk).

## Implementation Outcome Notes (2026-02-20)

- Filament was upgraded to `v5.2.1` successfully.
- No additional Filament plugin/extension constraints were required in `composer.json` (no plugin bumps).
- Composer resolution included transitive framework updates (not plugin-specific), including Laravel `v12.52.0` and Livewire `v4.1.4`.
- During verification, a tenant-scope regression surfaced in backup-set listing tests after the upgrade; mitigation was applied by explicitly scoping `BackupSetResource` queries to the active tenant.