organizations 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fba49577a4eb70a0bd69d5b554609a3a3b5a73046f1b0007219773b2e3cccd48
-  data.tar.gz: 8eba41990e24a6558de87d4760fabf09b65561fd43e4314e27f58ec5d838dbc3
+  metadata.gz: cee8b956413b0859d592b794078046a1f5ed95fea6fd391e8b3a6aee83dbc14d
+  data.tar.gz: 3f0ef38dd0d343ffbba6c7f9a28f1943f55f2610d90b77b36306908b79d18e64
 SHA512:
-  metadata.gz: f49c6a4eba6854e3988c2a39d175f5616af10ef8723e3c6f91d461ca8f3bc4151cb9ddc64e0baf5ff5a83e474690eacc86362d149354c46e72c97b92bf2e9c7a
-  data.tar.gz: 9b83cc21331c095d64ea22ba5f4874a11716e634f2dffd664a7b5b3ed4768c9ac048e2f03a4c93bddd92e3661d6003dceeac0edc21f671c5ff327dff4241490e
+  metadata.gz: fa931ef4f5a12370ae4f86ceb15bc9d601a35ef042db467cc9c4c4ff125022f16760fbfe1c9a140c0a3001862b61386d7a2529e1e2074be2b98576760983747f
+  data.tar.gz: a33b77589dc25b53c5a0783899d4056ac8a0fcb73e578f089eb3fece8565a3ae9c2f098c3c64babf43e752907807064ad3e78a0855b1e5a858631749bcce8461

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-24
+
+**Hand a personal organization over, and keep organizations that hold records with a retention period.** An invoicing app on the fleet built both by hand and runs them in production. This release moves them into the gem, with their tests. Both are opt-in, and no migration is needed.
+
+### Added
+
+- **Hand a personal organization over.** The need: the owner confirms that a member takes over their personal workspace, which then becomes shared, and a refused handover must leave nothing half done. `org.transfer_ownership_to!(admin, convert_to_shared: true)` makes a personal organization shared and transfers it in one step, in its own savepoint. A refused transfer leaves it personal, also when the caller rescues the error inside its own transaction, and the record in memory is read again. The transfer locks the new owner's row before the organization row, as the deletion guard does. A transfer to the personal owner itself is still refused. `config.convert_personal_organizations_on_transfer = true` makes the conversion the default, also for the engine's transfer action. The default (`false`) keeps the refusal of 0.7.0.
+- **Keep organizations that hold records with a retention period.** The need: an organization that holds records the law makes you keep, such as issued invoices or the books, must never be destroyed when its owner deletes their account. `config.retain_organization = ->(organization) { ... }` (default `nil`) names those organizations. `user.account_deletion_plan.organizations_to_retain` lists them apart from `organizations_to_destroy`. They do not block, so `allowed?` is unchanged. `user.destroy` returns false while the user owns one, with a message that names it, and the app closes the account instead. Any other destroy of a retained organization raises `Organizations::Organization::CannotDestroyRetainedOrganization` before any row goes. The destroy reads the organization again under its row lock, and the rule gets that copy, so a stale record cannot destroy it. Whatever creates the retained records must lock the organization row, or insert them with a foreign key that restricts deletion. The engine's controllers answer the error with a redirect back and the message (HTML), or a 422 (JSON).
+
+### Changed
+
+- `AccountDeletionPlan#to_h` has an `organizations_to_retain` key. It is an empty list when nothing is retained.
+- `user.destroy` takes its locks before its first write. It locks the user row, then the row of every organization in which it writes, in id order: its memberships, the invitations it sent and their grants, the memberships it invited, its join requests, the requests it decided, its join codes, the allowlist entries it claimed, the domains it verified and the grants it gave. Before, it locked only the owned organizations, after it deleted the grants of its sent invitations. **The callback order changes:** a new first `before_destroy` callback, `lock_rows_for_deletion`, takes the locks. It runs before `drop_grants_of_sent_invitations` and the guard, which keep their order and their names.
+- Every organization destroy locks its row before its `dependent: :destroy` cascades, with or without `retain_organization`. With the account deletion above, both paths take the organization row first. Before, a member's account deletion and a destroy of their organization could deadlock on PostgreSQL.
+- The account-deletion guard reads its plan with the query cache off. Before, a plan built earlier in the same request (a confirmation screen's preview) could answer from the cache, and miss a member that another connection had added.
+
+### Upgrading
+
+No migration is needed, and nothing changes until you set one of the two options. An app that prepends its own `transfer_ownership_to!` to convert personal organizations can remove it and set `config.convert_personal_organizations_on_transfer = true`. An app that refuses the destroy of such organizations in its own `before_destroy` can remove it and set `config.retain_organization`.
+
 ## [0.7.1] - 2026-10-19
 
 **A user whose invitation was accepted can now be deleted.** A patch release with one fix and one README correction. No migration is needed.

data/README.md

@@ -575,6 +575,7 @@ user.create_personal_organization!           # Create it, or return the existing
 
 # Account deletion
 user.account_deletion_plan                   # What user.destroy would do (changes nothing)
+Organizations::AccountDeletionPlan.for(user, lock: true)  # The same plan under the guard's locks
 ```
 
 ### Organization methods
@@ -604,7 +605,7 @@ Organizations::Organization.backfill_personal_owners!(mapping, dry_run: true)
 # Personal organizations
 org.personal?                   # "Is this someone's personal organization?"
 org.personal_owner              # The user it belongs to
-org.convert_to_shared!          # Stop being personal (needed before a transfer)
+org.convert_to_shared!          # Stop being personal
 
 # Actions
 # Pass the acting user (removed_by:, changed_by:) so the role rule is checked;
@@ -613,6 +614,7 @@ org.add_member!(user, role: :member)            # no actor: never checked, autho
 org.remove_member!(user, removed_by: current_user)
 org.change_role_of!(user, to: :admin, changed_by: current_user)
 org.transfer_ownership_to!(other_user)
+org.transfer_ownership_to!(other_user, convert_to_shared: true)  # Hand over a personal org: it becomes shared
 
 # Invitations (inviter must be a member with :invite_members permission)
 org.send_invite_to!(email)                  # Auto-infers invited_by from Current.user
@@ -1523,7 +1525,7 @@ Organizations::Organization.not_personal # every other organization
 The rules:
 
 - The link is `organizations.personal_owner_id`, with a unique index. A user has at most one personal organization.
-- The personal owner is also the owner membership. The gem writes both together, and `create_with_owner!` and `create_organization!` refuse a `personal_owner` who is not the new owner. `org.transfer_ownership_to!` raises `CannotTransferPersonalOrganization` for a personal organization: call `org.convert_to_shared!` first.
+- The personal owner is also the owner membership. The gem writes both together, and `create_with_owner!` and `create_organization!` refuse a `personal_owner` who is not the new owner. `org.transfer_ownership_to!` raises `CannotTransferPersonalOrganization` for a personal organization, so that nobody's own workspace moves by accident. To hand it over, see below.
 - A personal organization can have other members. To keep it owner-only, veto joins in the membership gate, which covers every join path:
 
   ```ruby
@@ -1546,6 +1548,25 @@ The rules:
 
   Conflict reasons: `:organization_not_found`, `:not_the_owner`, `:organization_personal_for_another_user`, `:user_has_another_personal_organization`, `:organization_mapped_twice`, `:user_mapped_twice`. The write runs in its own savepoint: a conflict found at write time (a concurrent provisioning) rolls back every assignment and comes back in the report.
 
+**Hand a personal organization over.** When your transfer screen tells the owner that the workspace becomes shared, and the owner confirms, convert and transfer in one step:
+
+```ruby
+org.transfer_ownership_to!(admin, convert_to_shared: true)
+org.personal?   # => false
+org.owner       # => admin
+```
+
+To make this the default, also for the engine's transfer action:
+
+```ruby
+config.convert_personal_organizations_on_transfer = true   # default: false
+```
+
+- The conversion and the transfer run in one savepoint. A refused transfer (the new owner is not an admin, say) leaves the organization personal, also when you rescue the error inside a transaction of yours. The record in memory is read again, so it does not say shared either.
+- A transfer to the personal owner itself still raises `CannotTransferPersonalOrganization`: there is nothing to hand over.
+- The transfer locks the new owner's row before the organization row, the order of the deletion guard, so it cannot deadlock with a deletion of the new owner.
+- `convert_to_shared: false` refuses again for one call.
+
 A personal organization tells you who probably pays. Billing and entitlements stay with your app.
 
 ## Deleting user accounts
@@ -1559,6 +1580,7 @@ plan = user.account_deletion_plan
 plan.allowed?                  # => false
 plan.blockers                  # => [#<struct organization=#<Organization "Acme">, reason=:owns_organization_with_members>]
 plan.organizations_to_destroy  # organizations deleted with the account
+plan.organizations_to_retain   # organizations kept, see "Organizations that must be kept"
 plan.memberships_to_remove     # the user's other memberships, removed with the account
 plan.to_h                      # ids and symbols, for an audit log or a confirmation screen
 user.account_deletion_plan(policy: :destroy_personal_organization)  # preview another policy
@@ -1582,9 +1604,48 @@ What the gem guarantees:
 
 - It checks the complete owned set before it deletes anything. One blocker blocks the whole deletion.
 - The organization deletion and the user deletion are one transaction, with its own savepoint, also inside a transaction of yours. A host `before_destroy` veto on the organization, or any later failure, rolls back everything, and the veto message is on `user.errors`.
-- The guard locks the user row and then the owned organization rows. A concurrent join or organization creation for that user, a join or transfer in an owned organization, and an ownership transfer to that user (`transfer_ownership_to!` locks the new owner's row) wait for the deletion, or finish first and are seen by it.
+- Before its first write, `user.destroy` locks the user row, then the row of every organization in which it writes (memberships, sent invitations and their grants, join requests and the other records it nullifies), in id order. An organization's destroy also locks its row before its cascades, so the two cannot deadlock. A concurrent join or organization creation for that user, a join, transfer or destroy in one of those organizations, and an ownership transfer to that user (`transfer_ownership_to!` locks the new owner's row) wait for the deletion, or finish first and are seen by it. The guard reads the database under its locks, not the query cache.
 - The user's other memberships are deleted (`dependent: :destroy`), as before. Invitations they sent, join requests they decided, join codes they created and allowlist entries they claimed keep the record and lose the user reference.
 
+### Organizations that must be kept
+
+Some organizations hold records that the law makes you keep for years, such as issued invoices or the books. Deleting the user must never destroy such an organization. Tell the gem which ones they are:
+
+```ruby
+config.account_deletion_policy = :destroy_personal_organization
+config.retain_organization = ->(organization) { organization.invoices.exists? }   # default: nil
+```
+
+The plan lists them apart. They do not block, so `allowed?` still answers the ownership question:
+
+```ruby
+plan = user.account_deletion_plan
+plan.allowed?                  # => true
+plan.organizations_to_retain   # => [#<Organization "Ana's books">]
+plan.organizations_to_destroy  # => []
+```
+
+- `user.destroy` returns false while the user owns a retained organization, because the organization would lose its owner. `user.errors` names each one: "Ana's books holds records that must be kept, so it cannot be deleted." Reword it with the `organizations.errors.organization_retained` key.
+- Close the account in your app instead. Lock the user row, then build the plan under locks (the guard's order). Keep the retained organizations, delete the rest, and anonymize the user row:
+
+  ```ruby
+  User.transaction do
+    user.lock!
+    plan = Organizations::AccountDeletionPlan.for(user, lock: true)
+    raise "Transfer or delete the blocking organizations first" unless plan.allowed?
+
+    plan.organizations_to_retain.each { |organization| organization.close! }  # your app's closure
+    plan.organizations_to_destroy.each(&:destroy!)
+    plan.memberships_to_remove.each(&:destroy!)
+    user.anonymize!                                                          # your app's anonymization
+  end
+  ```
+
+- Every other destroy of a retained organization raises `Organizations::Organization::CannotDestroyRetainedOrganization` before any row goes: an admin screen, a console, a cascade. The engine's controllers answer it like a refused form: HTML goes back with the message as an alert, JSON gets a 422 with `{ "error": message }`. `delete` and `delete_all` skip callbacks, so they skip this check too.
+- The rule gets the organization read again under its row lock, and the lock holds until the destroy commits. The rule runs with the query cache off. A stale copy, a cached association or a cached query cannot let a retained organization go. A record added after the preview still keeps the organization.
+- Whatever creates the retained records must lock the organization row (`organization.lock!` in the same transaction), or insert them with a foreign key to the organization that restricts deletion. Then a concurrent destroy waits for the record and sees it, or the database refuses the delete.
+- An organization that blocks (shared, or with other members) stays a blocker. Under `:prevent` nothing is listed as retained, because nothing would be deleted.
+
 ## User Onboarding Patterns
 
 The `always_create_personal_organization_for_each_user` setting controls how new users get their first organization. This is one of the most important decisions when integrating the gem.
@@ -1777,6 +1838,14 @@ Organizations.configure do |config|
   # when they are its only member. See "Deleting user accounts".
   config.account_deletion_policy = :prevent
 
+  # Organizations that hold records with a retention period: never destroyed
+  # (default: nil). See "Organizations that must be kept".
+  config.retain_organization = nil
+
+  # transfer_ownership_to! makes a personal organization shared and transfers
+  # it, instead of refusing (default: false). See "Personal organizations".
+  config.convert_personal_organizations_on_transfer = false
+
   # === Invitations ===
   # How long invitations are valid
   config.invitation_expiry = 7.days

data/app/controllers/organizations/application_controller.rb

@@ -27,6 +27,10 @@ module Organizations
     # Ensure user is authenticated for all actions
     before_action :authenticate_organizations_user!
 
+    # A retained organization (config.retain_organization) refuses every
+    # destroy. Answer that like a refused form, not with an error page.
+    rescue_from Organizations::Organization::CannotDestroyRetainedOrganization, with: :respond_organization_retained
+
     # Expose current_user to views (ControllerHelpers exposes org-related helpers)
     helper_method :current_user
 
@@ -67,6 +71,15 @@ module Organizations
     # Alias for compatibility
     alias_method :current_organizations_user, :current_user
 
+    # Nothing changed: the destroy rolled back, and the current organization
+    # stays in the session.
+    def respond_organization_retained(error)
+      respond_to do |format|
+        format.html { redirect_back fallback_location: main_app.root_path, alert: error.message }
+        format.json { render json: { error: error.message }, status: 422 }
+      end
+    end
+
     def organizations_authenticated_layout
       configured_layout = Organizations.configuration.authenticated_controller_layout
       return nil if configured_layout.nil?

data/config/locales/en.yml

@@ -114,6 +114,7 @@ en:
       organization_limit_reached: "Maximum number of organizations (%{max}) reached"
       no_current_organization_to_leave: "No current organization to leave"
       cannot_delete_user_owns_organizations: "Cannot delete a user who still owns organizations. Transfer ownership or delete those organizations first."
+      organization_retained: "%{organization} holds records that must be kept, so it cannot be deleted."
 
       # — Controller guards (default unauthorized copy) —
       unauthorized_role: "You need %{role} access to perform this action"

data/config/locales/es.yml

@@ -94,6 +94,7 @@ es:
       organization_limit_reached: "Has alcanzado el máximo de organizaciones (%{max})"
       no_current_organization_to_leave: "No hay ninguna organización activa de la que salir"
       cannot_delete_user_owns_organizations: "No se puede eliminar un usuario que aún es propietario de organizaciones. Transfiere la propiedad o elimina esas organizaciones primero."
+      organization_retained: "%{organization} contiene registros que se deben conservar, así que no se puede eliminar."
 
       unauthorized_role: "Necesitas acceso de %{role} para hacer esto"
       unauthorized_permission: "No tienes permiso para %{permission}"

data/lib/organizations/account_deletion_plan.rb

@@ -10,6 +10,7 @@ module Organizations
   #   plan.allowed?                  # => false
   #   plan.blockers                  # => [#<Blocker organization=…, reason=:owns_organization_with_members>]
   #   plan.organizations_to_destroy  # personal organizations deleted with the account
+  #   plan.organizations_to_retain   # organizations that config.retain_organization keeps
   #   plan.memberships_to_remove     # the user's other memberships, removed with the account
   #
   # Blocker reasons:
@@ -18,6 +19,14 @@ module Organizations
   #   :personal_organization_with_members - the personal organization has other members
   #   :personal_organization              - the policy is :prevent
   #
+  # Retained organizations (config.retain_organization) are the ones that
+  # the policy would delete with the account, but that hold records the app
+  # must keep. They do not block: allowed? stays about ownership. But
+  # user.destroy refuses while there is one, because it would leave the
+  # organization without its owner. The app closes the account instead: it
+  # keeps those organizations, destroys organizations_to_destroy and
+  # memberships_to_remove, and anonymizes the user.
+  #
   # Database effects only. Subscriptions, external services and retained
   # records belong to the host's account-closure workflow: a rollback cannot
   # undo an external call, so run those after the deletion commits.
@@ -31,7 +40,7 @@ module Organizations
       personal_organization
     ].freeze
 
-    attr_reader :user, :policy, :blockers, :organizations_to_destroy, :memberships_to_remove
+    attr_reader :user, :policy, :blockers, :organizations_to_destroy, :organizations_to_retain, :memberships_to_remove
 
     # @param user [User]
     # @param policy [Symbol] one of Configuration::ACCOUNT_DELETION_POLICIES
@@ -49,11 +58,15 @@ module Organizations
       @policy = policy
       @blockers = []
       @organizations_to_destroy = []
-      classify(owned_organizations(lock: lock))
-      @memberships_to_remove = remaining_memberships
+      @organizations_to_retain = []
+      # Under locks, read the database. The query cache can hold an answer
+      # from earlier in the request, from before another connection
+      # committed (a new member, a retained record).
+      lock ? ActiveRecord::Base.uncached { build(lock) } : build(lock)
     end
 
-    # @return [Boolean] true when the user can be deleted
+    # @return [Boolean] true when no owned organization blocks the deletion.
+    #   With organizations_to_retain, the account closes instead.
     def allowed?
       blockers.empty?
     end
@@ -66,12 +79,18 @@ module Organizations
         policy: policy,
         blockers: blockers.map { |b| { organization_id: b.organization.id, reason: b.reason } },
         organizations_to_destroy: organizations_to_destroy.map(&:id),
+        organizations_to_retain: organizations_to_retain.map(&:id),
         memberships_to_remove: memberships_to_remove.map(&:id)
       }
     end
 
     private
 
+    def build(lock)
+      classify(owned_organizations(lock: lock))
+      @memberships_to_remove = remaining_memberships
+    end
+
     # Organizations the user owns, plus any organization still linked to them
     # as personal owner (a raw write can leave a link without the membership).
     def owned_organizations(lock:)
@@ -83,18 +102,25 @@ module Organizations
     end
 
     def classify(organizations)
-      @shared_ids = Membership.where(organization_id: organizations.map(&:id)).where.not(user_id: user.id)
-        .distinct.pluck(:organization_id).to_set
+      @shared_ids = shared_organization_ids(organizations)
       organizations.each do |organization|
         reason = blocker_reason(organization)
         if reason
           blockers << Blocker.new(organization: organization, reason: reason)
+        elsif Organizations.configuration.retain_organization?(organization)
+          organizations_to_retain << organization
         else
           organizations_to_destroy << organization
         end
       end
     end
 
+    # The owned organizations that have a member other than this user
+    def shared_organization_ids(organizations)
+      Membership.where(organization_id: organizations.map(&:id)).where.not(user_id: user.id)
+        .distinct.pluck(:organization_id).to_set
+    end
+
     def blocker_reason(organization)
       others = @shared_ids.include?(organization.id)
       personal = personal_column? && organization.personal_owner_id == user.id

data/lib/organizations/configuration.rb

@@ -93,6 +93,27 @@ module Organizations
     # as before. Needs the personal_owner_id column (rails g organizations:upgrade).
     attr_accessor :record_personal_organizations
 
+    # The default of transfer_ownership_to!(new_owner, convert_to_shared:).
+    # false (default): a personal organization raises
+    # CannotTransferPersonalOrganization. true: the transfer makes it shared
+    # first, in the same step. Turn it on when your transfer screen tells the
+    # owner that the workspace becomes shared. The engine's transfer action
+    # uses this default.
+    attr_accessor :convert_personal_organizations_on_transfer
+
+    # Organizations that must be kept because they hold records with a
+    # retention period (issued invoices, the books). A callable that receives
+    # the organization and returns true to keep it. nil (default) keeps
+    # nothing. Deleting the user never destroys a kept organization:
+    # user.account_deletion_plan lists it in organizations_to_retain,
+    # user.destroy refuses while the user owns one, and any destroy of it
+    # raises Organization::CannotDestroyRetainedOrganization. Your app closes
+    # it instead. The callable gets the organization read again under its
+    # row lock, so whatever creates the retained records must lock that row
+    # too, or insert them with a foreign key to it that restricts deletion.
+    #   config.retain_organization = ->(organization) { organization.invoices.exists? }
+    attr_accessor :retain_organization
+
     # What happens when a user who owns organizations is deleted:
     #   :prevent (default)              - any owned organization blocks the deletion
     #   :destroy_personal_organization  - the user's personal organization is
@@ -339,6 +360,8 @@ module Organizations
       @always_create_personal_organization_for_each_user = false
       @default_organization_name = "Personal"
       @record_personal_organizations = false
+      @convert_personal_organizations_on_transfer = false
+      @retain_organization = nil
       @vocabulary = nil
       @full_resource_access_role = :admin
       @grant_capabilities = nil
@@ -601,6 +624,18 @@ module Organizations
       Array(@blocked_email_domains).map { |d| d.to_s.strip.downcase.delete_prefix("@") }
     end
 
+    # @api private
+    # Whether config.retain_organization keeps this organization
+    # @param organization [Organizations::Organization]
+    # @return [Boolean]
+    def retain_organization?(organization)
+      return false unless @retain_organization
+
+      # Not from the query cache: a request can have cached "no retained
+      # records" before another connection committed one.
+      ActiveRecord::Base.uncached { @retain_organization.call(organization) } ? true : false
+    end
+
     # @api private
     # Resolve the default organization name for a user
     # @param user [Object] The user object
@@ -682,6 +717,11 @@ module Organizations
         raise ConfigurationError, "record_personal_organizations must be true or false"
       end
 
+      unless [true, false].include?(@convert_personal_organizations_on_transfer)
+        raise ConfigurationError, "convert_personal_organizations_on_transfer must be true or false"
+      end
+
+      validate_callable_option!(@retain_organization, "retain_organization")
       return if ACCOUNT_DELETION_POLICIES.include?(@account_deletion_policy)
 
       raise ConfigurationError, "account_deletion_policy must be one of: #{ACCOUNT_DELETION_POLICIES.join(', ')}"

data/lib/organizations/models/concerns/has_organizations.rb

@@ -185,6 +185,8 @@ module Organizations
             # this user attached to pending invitations die with the account,
             # so an orphaned invitation never hands out unchecked access.
             before_destroy :drop_grants_of_sent_invitations, prepend: true
+            # First of all, before any write of this destroy: the locks.
+            before_destroy :lock_rows_for_deletion, prepend: true
           end
         end
 
@@ -774,32 +776,73 @@ module Organizations
 
           # The account-deletion guard (config.account_deletion_policy). Runs
           # inside the destroy transaction, before the dependent memberships
-          # are destroyed. It locks this user's row first, so a concurrent
-          # join or organization creation for this user waits, then locks the
-          # owned organizations, so a concurrent join or transfer in them
-          # waits too. It checks the complete owned set before it deletes
-          # anything; a blocker, or any failure, aborts the whole destroy and
-          # rolls back every organization deleted so far.
+          # are destroyed, and after lock_rows_for_deletion took the user row
+          # and the organization rows. It checks the complete owned set
+          # before it deletes anything; a blocker, a retained organization,
+          # or any failure, aborts the whole destroy and rolls back every
+          # organization deleted so far.
           def prevent_deletion_while_owning_organizations
-            lock_own_row_for_deletion
             plan = Organizations::AccountDeletionPlan.for(self, lock: true)
             unless plan.allowed?
               errors.add(:base, Organizations.t(:"errors.cannot_delete_user_owns_organizations"))
               throw(:abort)
             end
 
+            refuse_deletion_while_retaining(plan.organizations_to_retain)
             plan.organizations_to_destroy.each { |organization| destroy_personal_organization_for_deletion(organization) }
             memberships.reset if plan.organizations_to_destroy.any?
           end
 
+          # A retained organization must keep its records and its owner, so
+          # the user row stays: the app closes the account instead. The
+          # message names each organization, as a veto on its destroy would.
+          def refuse_deletion_while_retaining(organizations)
+            return if organizations.empty?
+
+            organizations.each do |organization|
+              errors.add(:base, Organizations.t(:"errors.organization_retained", organization: organization))
+            end
+            throw(:abort)
+          end
+
           def drop_grants_of_sent_invitations
             return unless Organizations::GrantHolder.grants_table?
 
             Organizations::Grant.where(invitation_id: sent_organization_invitations.select(:id)).delete_all
           end
 
-          def lock_own_row_for_deletion
+          # The user row, then the row of every organization in which this
+          # destroy writes, in id order, before its first write. The user row
+          # keeps a concurrent join, organization creation or transfer to
+          # this user out. An organization's destroy locks its row before its
+          # cascades write the child rows, so with the organization rows
+          # first both paths take one order and cannot deadlock. The id order
+          # keeps two account deletions apart.
+          def lock_rows_for_deletion
             self.class.unscoped.where(self.class.primary_key => id).lock.pick(self.class.primary_key)
+            organizations = Organizations::Organization
+            scope = organization_ids_written_by_deletion.map { |ids| organizations.where(id: ids) }.reduce(:or)
+            scope = scope.or(organizations.where(personal_owner_id: id)) if organizations.column_names.include?("personal_owner_id")
+            scope.order(:id).lock.pluck(:id)
+          end
+
+          # The organizations of the rows this destroy deletes or nullifies:
+          # the dependent: options of has_organizations, the grant cleanup,
+          # and the ON DELETE rules of the install migrations.
+          def organization_ids_written_by_deletion
+            relations = [
+              Organizations::Membership.where(user_id: id), Organizations::Membership.where(invited_by_id: id),
+              Organizations::Invitation.where(invited_by_id: id),
+              Organizations::JoinRequest.where(user_id: id), Organizations::JoinRequest.where(decided_by_id: id),
+              Organizations::JoinCode.where(created_by_id: id), Organizations::AllowlistEntry.where(claimed_by_id: id)
+            ]
+            relations << Organizations::Domain.where(verified_by_id: id) if Organizations::Domain.authority_columns?
+            if Organizations::GrantHolder.grants_table?
+              granted = Organizations::Grant.where(granted_by_id: id)
+              relations << Organizations::Membership.where(id: granted.select(:membership_id))
+              relations << Organizations::Invitation.where(id: granted.select(:invitation_id))
+            end
+            relations.map { |relation| relation.select(:organization_id) }
           end
 
           def destroy_personal_organization_for_deletion(organization)

data/lib/organizations/models/organization.rb

@@ -32,6 +32,7 @@ module Organizations
     class NoOwnerPresent < Organizations::Error; end
     class MemberAlreadyExists < Organizations::Error; end
     class CannotTransferPersonalOrganization < Organizations::Error; end
+    class CannotDestroyRetainedOrganization < Organizations::Error; end
 
     # === Associations ===
 
@@ -87,6 +88,11 @@ module Organizations
                class_name: Organizations.user_class_name,
                optional: true
 
+    # Before the dependent: :destroy cascades: lock the row, so that every
+    # path takes the organization row before its memberships and
+    # invitations, and keep a retained organization (config.retain_organization).
+    before_destroy :lock_row_and_refuse_if_retained, prepend: true
+
     # === Validations ===
 
     validates :name, presence: true
@@ -186,7 +192,9 @@ module Organizations
     end
 
     # Stop treating this organization as the owner's personal organization.
-    # Do this before you transfer its ownership. Members, roles and data stay.
+    # Members, roles and data stay. To hand it over to another member, use
+    # transfer_ownership_to!(member, convert_to_shared: true), which does
+    # both in one step.
     # @return [self]
     def convert_to_shared!
       update!(personal_owner_id: nil)
@@ -426,32 +434,35 @@ module Organizations
     # The new owner must be an admin of the organization
     # Old owner becomes admin
     # @param new_owner [User] The user to become owner
+    # @param convert_to_shared [Boolean] for a personal organization: make it
+    #   shared and transfer it in one step (default:
+    #   config.convert_personal_organizations_on_transfer). A refused transfer
+    #   leaves it personal. A transfer to the personal owner itself is still
+    #   refused.
     # @raise [CannotTransferToNonMember] if user is not a member
     # @raise [CannotTransferToNonAdmin] if user is not an admin
-    def transfer_ownership_to!(new_owner)
-      ActiveRecord::Base.transaction do
+    # @raise [CannotTransferPersonalOrganization] for a personal organization
+    #   without convert_to_shared
+    def transfer_ownership_to!(
+      new_owner, convert_to_shared: Organizations.configuration.convert_personal_organizations_on_transfer
+    )
+      converting = false
+      # A conversion gets its own savepoint: a refusal after it (the new owner
+      # is not an admin, say) undoes it, also when the caller rescues the
+      # error inside a transaction of its own.
+      ActiveRecord::Base.transaction(requires_new: convert_to_shared) do
         lock_new_owner_row!(new_owner)
         lock! # then the organization row, to prevent concurrent operations
 
-        ensure_not_personal_for_transfer!
-
-        # Always perform a fresh read in this write path, even if memberships
-        # are preloaded on this instance, to avoid stale-owner selection.
-        old_owner_membership = memberships.find_by(role: "owner")
-        new_owner_membership = memberships.find_by(user_id: new_owner.id)
-
-        unless old_owner_membership
-          raise NoOwnerPresent, Organizations.t(:"errors.transfer_no_owner", organization: self)
-        end
-
-        unless new_owner_membership
-          raise CannotTransferToNonMember, Organizations.t(:"errors.transfer_to_non_member", organization: self)
+        # Read under the lock: lock! read the personal link again. A transfer
+        # to the personal owner itself converts nothing, so it is refused.
+        if convert_to_shared && personal? && personal_owner_id != new_owner.id
+          converting = true
+          convert_to_shared!
         end
+        ensure_not_personal_for_transfer!
 
-        # New owner must be at least an admin (per README: "Ownership can be transferred to any admin")
-        unless Roles.at_least?(new_owner_membership.role.to_sym, :admin)
-          raise CannotTransferToNonAdmin, Organizations.t(:"errors.transfer_to_non_admin", organization: self)
-        end
+        old_owner_membership, new_owner_membership = memberships_for_transfer!(new_owner)
 
         # No-op transfer to the current owner.
         return old_owner_membership if old_owner_membership.user_id == new_owner.id
@@ -474,6 +485,11 @@ module Organizations
           new_owner: new_owner
         )
       end
+    rescue StandardError
+      # Only a started conversion changed this copy. A refusal before it (a
+      # record with unsaved changes cannot be locked) keeps those changes.
+      forget_refused_conversion if converting
+      raise
     end
 
     # === Invitation Methods ===
@@ -753,8 +769,56 @@ module Organizations
       raise CannotTransferToNonMember, Organizations.t(:"errors.transfer_to_non_member", organization: self)
     end
 
-    # A personal organization belongs to its owner. Call convert_to_shared!
-    # first to move it to someone else.
+    # The savepoint undid the conversion, but this copy can still say shared.
+    # Read it again. A reload that fails must not hide why the transfer was
+    # refused.
+    def forget_refused_conversion
+      reload if persisted?
+    rescue ActiveRecord::ActiveRecordError
+      nil
+    end
+
+    # The owner's and the new owner's memberships, read fresh in this write
+    # path even if memberships are preloaded on this instance, to avoid a
+    # stale owner. The new owner must be at least an admin (README:
+    # "Ownership can be transferred to any admin").
+    def memberships_for_transfer!(new_owner)
+      old_owner_membership = memberships.find_by(role: "owner")
+      new_owner_membership = memberships.find_by(user_id: new_owner.id)
+
+      raise NoOwnerPresent, Organizations.t(:"errors.transfer_no_owner", organization: self) unless old_owner_membership
+
+      unless new_owner_membership
+        raise CannotTransferToNonMember, Organizations.t(:"errors.transfer_to_non_member", organization: self)
+      end
+
+      unless Roles.at_least?(new_owner_membership.role.to_sym, :admin)
+        raise CannotTransferToNonAdmin, Organizations.t(:"errors.transfer_to_non_admin", organization: self)
+      end
+
+      [old_owner_membership, new_owner_membership]
+    end
+
+    # Every destroy locks the organization row before the cascades delete
+    # its memberships and invitations. The account-deletion guard also locks
+    # organization rows before it writes their child rows, so the two paths
+    # take the same order and cannot deadlock.
+    #
+    # A record with a retention period must outlive every destroy path, not
+    # only the account deletion: an admin screen, a console, a cascade.
+    # This copy can be stale (attributes, cached associations), so the rule
+    # gets the row read again under the lock. The lock holds until the
+    # destroy and its cascades commit, so a writer that locks the row, or
+    # inserts a row with a foreign key to it, waits or is seen.
+    def lock_row_and_refuse_if_retained
+      current = self.class.unscoped.lock.find_by(self.class.primary_key => id)
+      return unless current && Organizations.configuration.retain_organization?(current)
+
+      raise CannotDestroyRetainedOrganization, Organizations.t(:"errors.organization_retained", organization: current)
+    end
+
+    # A personal organization belongs to its owner. Pass convert_to_shared:
+    # true, or call convert_to_shared! first, to move it to someone else.
     def ensure_not_personal_for_transfer!
       return unless personal?
 

data/lib/organizations/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Organizations
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: organizations
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties