♻️ refactor(ownership): move to polymorphic relationship for governed models

[mikebronner]

Summary

Refactors model ownership tracking from the governor_owned_by column approach to a polymorphic relationship via a new governor_ownables pivot table. The old column is deprecated but preserved for backward compatibility.

Changes

• GovernorOwnable model — new Eloquent model for the governor_ownables polymorphic pivot table with ownable() MorphTo and owner() BelongsTo relationships
• Governable trait — added governorOwner() MorphOne relationship; getGovernorOwnedByAttribute and getOwnedByAttribute accessors now read from polymorphic table with fallback to deprecated column
• N+1 fix — removed unsetRelation('governorOwner') calls from accessors and BasePolicy so eager loading works correctly
• CreatedListener — creates GovernorOwnable record on model creation via firstOrCreate; handles auth user, explicit column value, and no-owner paths
• CreatingListener — maintains backward compat by still setting the deprecated governor_owned_by column
• CreatingInvitationListener — uses conditional auth check instead of direct ownedBy() association
• Team — transferOwnership() creates/updates polymorphic record; getOwnerNameAttribute falls back through polymorphic → deprecated owner
• Governing trait — new governorOwnedTeams() method for polymorphic team ownership lookup
• TeamInvitation notification — null-safe accessors for owner/team names
• LaravelGovernorUpgradeTo0130 seeder — migrates existing governor_owned_by column data to the polymorphic table
• Migration — create_governor_ownables_table with morphs columns and unique constraint
• Binary sqlite removed — tests/database/database.sqlite removed from Git tracking

Acceptance Criteria

• Governed models use polymorphic relationships instead of direct foreign keys
• Migration is provided to move existing data to the new structure without data loss
• All Governor queries and policies work correctly after the migration

Test Coverage

• Unit test: governed model can be attached/detached via polymorphic relationship
• Integration test: migration runs cleanly on existing data
• Regression test: all existing policy and permission checks pass after refactor

Test Coverage

• PolymorphicOwnershipTest (16 tests) — GovernorOwnable model, governorOwner() MorphOne, attach/detach, accessors, eager loading, fallback to deprecated column
• UpgradeTo0130SeederTest (3 tests) — migration seeder execution, idempotency, empty model set handling
• CreatedListenerTest — polymorphic ownership creation for governable/non-governable models, explicit owner, no-auth paths
• CreatingInvitationListenerTest (3 tests) — auth-conditional ownership, polymorphic record creation, no-auth behavior
• TransferOwnershipTest — polymorphic record creation/update on transfer, relation clearing, ownerName fallback
• GoverningTest (3 tests) — governorOwnedTeams() filtering, exclusion, empty collection
• TeamInvitationTest — null-safe owner/team name handling in notification
• 349 total tests, 596 assertions — all passing across PHP 8.2–8.5, Laravel 11–13

Fixes #46

[codecov]

Codecov Report

❌ Patch coverage is 89.10891% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.59%. Comparing base (e3cc99c) to head (e633c18).

Files with missing lines	Patch %	Lines
src/Listeners/CreatedListener.php	79.48%	8 Missing ⚠️
src/Traits/Governable.php	85.00%	3 Missing ⚠️

❌ Your patch check has failed because the patch coverage (89.10%) is below the target coverage (90.00%). You can increase the patch coverage or adjust the target coverage.
❌ Your project check has failed because the head coverage (71.59%) is below the target coverage (90.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #120      +/-   ##
============================================
+ Coverage     70.65%   71.59%   +0.94%     
- Complexity      373      390      +17     
============================================
  Files            53       54       +1     
  Lines          1537     1609      +72     
============================================
+ Hits           1086     1152      +66     
- Misses          451      457       +6     

Files with missing lines	Coverage Δ
src/GovernorOwnable.php	100.00% <100.00%> (ø)
src/Listeners/CreatingInvitationListener.php	100.00% <100.00%> (ø)
src/Listeners/CreatingListener.php	94.73% <100.00%> (+0.29%)	⬆️
src/Notifications/TeamInvitation.php	82.60% <100.00%> (+1.65%)	⬆️
src/Policies/BasePolicy.php	88.54% <100.00%> (+0.24%)	⬆️
src/Team.php	84.21% <100.00%> (+3.77%)	⬆️
src/Traits/Governing.php	90.56% <100.00%> (-9.44%)	⬇️
src/Traits/Governable.php	88.57% <85.00%> (+1.90%)	⬆️
src/Listeners/CreatedListener.php	83.33% <79.48%> (+20.17%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mikebronner]

Review Checklist

• Test gap: no new tests for polymorphic ownership — The diff introduces GovernorOwnable, the governorOwner() relationship, the getGovernorOwnedByAttribute accessor, and the LaravelGovernorUpgradeTo0130 seeder — none of which have dedicated test coverage. The issue AC explicitly requires: (1) unit test for attach/detach via polymorphic relationship, (2) integration test for migration on existing data, (3) regression tests for policy checks post-refactor. The existing 321 tests pass (good), but they don't exercise the new polymorphic code paths directly. Codecov patch/project checks are failing, confirming coverage dropped.
• Performance: getGovernorOwnedByAttribute forces fresh query on every access — Line 113 of Governable.php calls $this->unsetRelation('governorOwner') before every access, preventing eager-loading from ever being used. If governor_owned_by is accessed in a loop (e.g., a policy check across a collection), this creates an N+1 query. Consider removing the unsetRelation call and letting normal eager-loading work, or document why forced-fresh is necessary.
• Binary sqlite committed — tests/database/database.sqlite is a binary diff. This makes schema changes invisible in review and causes merge conflicts. Consider generating the test DB from migrations at test setup instead.

[mikebronner]

Review Checklist

• CI: codecov/patch and codecov/project checks are failing. All test matrix jobs pass (10/10 PHP/Laravel combos green), but coverage gates must be green before approval. The new code in CreatedListener, CreatingListener, BasePolicy, Governable trait, Team, and GovernorOwnable needs sufficient test coverage to satisfy the patch threshold.