organizations 0.7.1 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fba49577a4eb70a0bd69d5b554609a3a3b5a73046f1b0007219773b2e3cccd48
-  data.tar.gz: 8eba41990e24a6558de87d4760fabf09b65561fd43e4314e27f58ec5d838dbc3
+  metadata.gz: e3c621c2b6bb7bd32be611858d49af9cb12cf9fa80bc0309d1227eafc819f8d8
+  data.tar.gz: c6028a9e424ab92432c44ae45bcba367d2a70eab56e3901314b1d5ff9b9b102f
 SHA512:
-  metadata.gz: f49c6a4eba6854e3988c2a39d175f5616af10ef8723e3c6f91d461ca8f3bc4151cb9ddc64e0baf5ff5a83e474690eacc86362d149354c46e72c97b92bf2e9c7a
-  data.tar.gz: 9b83cc21331c095d64ea22ba5f4874a11716e634f2dffd664a7b5b3ed4768c9ac048e2f03a4c93bddd92e3661d6003dceeac0edc21f671c5ff327dff4241490e
+  metadata.gz: 267e7126501538f4461616e2be708f1b3696a016b428135337193dc8eaf24532a446a9c651b1989610862025298cbb4b9ab38b7f1d901b0fcb3f49f68d28ec56
+  data.tar.gz: 98d2dbd1b5369c247c6b8147c7472f0b53e74aa25c0c000b8458834ddff6e81f0ec6f3e599611f2ba8ef10b2dd88ddb5775fe15816cef13d57fb48a393ddce6a

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 ## [Unreleased]
 
+## [0.8.1] - 2026-10-25
+
+**The joins take the lock order of the destroys.** A patch release with one fix. No migration is needed.
+
+### Fixed
+
+- **A join could deadlock with a deletion on PostgreSQL.** 0.8.0 made every destroy lock the user row, then the organization rows, then their child rows. Several joins locked their own row first, and the organization row (or a user row) only later, when they wrote. So a join and a deletion could each hold a row that the other waited for. PostgreSQL then aborted one of them with `ActiveRecord::Deadlocked`. These paths now take a guard on the user rows that their writes name (in id order), then lock the organization row, then their own row:
+  - `Invitation#accept!` (the accepting user and the inviter). Before, an acceptance deadlocked with the inviter's account deletion or with a destroy of the organization.
+  - `Invitation#revoke!` (no user row). Before, the revoke of an invitation with grants deadlocked with a destroy of its organization or with the inviter's account deletion.
+  - `JoinRequest#approve!` and the automatic approval after a verified email (the requester and the decider). Before, an approval deadlocked with the requester's account deletion.
+  - `JoinRequest#verify_email_code!` (the requester). Before, the check of an emailed code deadlocked with a destroy of the organization, which deletes the domain before the request. The requester's guard comes first, so the automatic approval inside a host transaction asks for no user row while it holds the organization row.
+  - `JoinCode#redeem!` (the redeeming user). Before, a redemption deadlocked with the account deletion of the code's creator or with a destroy of the organization.
+- **The user guard is a key share lock** (`FOR KEY SHARE` on PostgreSQL, a shared lock on MySQL, nothing on SQLite). It conflicts with the deletion's `FOR UPDATE`, and with nothing else: an update of the user and the foreign key checks of other writers pass. So `reject!` (which names its decider), `withdraw!`, `resend!` and a grant on a pending invitation (which names its granter) keep their single row lock and do not wait for the guards.
+- **An acceptance from a stale copy locks the current inviter.** A reissue of an expired invitation (`send_invite_to!`) names the new inviter. A loaded copy can still name the old one. The acceptance reads the row again under its lock. When the row names other ids than the ones locked, the acceptance releases its locks (a savepoint) and tries again with the current ids, up to three times. Then it raises `Invitation::InvitationChanged`, an `InvitationError`. `accept_pending_organization_invitation!` returns it as the failure `:invitation_changed` and keeps the session token. The engine's accept action answers with the localized message: HTML goes back to the invitation page, JSON gets a 409. Before, the acceptance could insert a membership that named an unlocked inviter, and deadlock with an ownership transfer to that inviter.
+- Inside a host transaction, the order holds only when the locks that the host took earlier in that transaction keep it too.
+- README: "Row-level locking" states the one lock order. The steps of the ownership transfer now start with the new owner's row, as the code has done since 0.7.0.
+
+## [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
@@ -720,6 +722,10 @@ invitation.grant!(record, capabilities: %i[read])
 # Actions
 invitation.accept!              # Accept (auto-infers Current.user)
 invitation.accept!(user)        # Accept with explicit user
+# accept! raises Organizations::InvitationExpired, Organizations::InvitationAlreadyAccepted,
+# Invitation::EmailMismatch, Invitation::CannotAcceptAsOwner, or Invitation::InvitationChanged:
+# a reissue named another inviter at each of three tries to lock the rows. Nothing is
+# written then, and the person can try again (organizations.errors.invitation_changed).
 invitation.resend!(resent_by: current_user)   # Send invitation email again
 invitation.revoke!(revoked_by: current_user)  # Delete it, so the link stops working
 ```
@@ -1323,6 +1329,8 @@ else
 end
 ```
 
+The reasons: `:missing_user`, `:missing_token`, `:invitation_not_found`, `:invitation_expired`, `:email_mismatch`, `:already_accepted_without_membership` and `:invitation_changed`. `:invitation_changed` means that a reissue changed the invitation during the acceptance (`Invitation::InvitationChanged`). Nothing was written, and the session keeps the token, so the person can try again. The engine's accept action answers it with the localized message (`organizations.errors.invitation_changed`): HTML goes back to the invitation page, JSON gets a 409 with `{ "error": message }`.
+
 Configure redirects in your initializer:
 
 ```ruby
@@ -1523,7 +1531,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 +1554,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 +1586,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 +1610,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. The joins take the same order (see "Row-level locking"). 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 +1844,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
@@ -2636,7 +2711,9 @@ These constraints prevent duplicate data at the database level:
 
 ### Row-level locking
 
-The gem uses `SELECT ... FOR UPDATE` (row-level locks) to prevent race conditions:
+The gem uses `SELECT ... FOR UPDATE` (row-level locks) to prevent race conditions.
+
+The gem takes its row locks in one order: the user rows that a write names (in id order), then the organization row, then the rows of the organization. A user's deletion locks its user row `FOR UPDATE`. The joins take a key share guard on their user rows (`FOR KEY SHARE` on PostgreSQL): only a deletion of those users waits for it, and ordinary updates and foreign key checks pass. A user's deletion, an organization's destroy, an invitation acceptance or revoke, a join request approval, the check of an emailed code and a join code redemption all keep this order. So they wait for each other, and do not deadlock on PostgreSQL. Inside your own transaction, the order holds only when your earlier locks in that transaction keep it too. Keep the same order in your own code that writes in an organization.
 
 **Invitation acceptance:**
 ```ruby
@@ -2644,11 +2721,14 @@ The gem uses `SELECT ... FOR UPDATE` (row-level locks) to prevent race condition
 invitation.accept!
 
 # Internally:
-# 1. Lock invitation row
-# 2. Check accepted_at is nil
-# 3. Create membership
-# 4. Set accepted_at
-# 5. Release lock
+# 1. Take the key share guard on the accepting user and the inviter
+# 2. Lock organization row
+# 3. Lock invitation row (when it now names another inviter, release the
+#    locks and start again with the current one, up to three times)
+# 4. Check accepted_at is nil
+# 5. Create membership
+# 6. Set accepted_at
+# 7. Release locks
 # Second request sees accepted_at is set, returns existing membership
 ```
 
@@ -2657,13 +2737,14 @@ invitation.accept!
 org.transfer_ownership_to!(new_owner)
 
 # Internally:
-# 1. Lock organization row
-# 2. Lock old owner's membership
-# 3. Lock new owner's membership
-# 4. Verify new owner is a member
-# 5. Demote old owner to admin
-# 6. Promote new owner to owner
-# 7. Release locks
+# 1. Lock the new owner's user row
+# 2. Lock organization row
+# 3. Lock old owner's membership
+# 4. Lock new owner's membership
+# 5. Verify new owner is a member
+# 6. Demote old owner to admin
+# 7. Promote new owner to owner
+# 8. Release locks
 ```
 
 **Last admin/owner protection:**

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/app/controllers/organizations/public_invitations_controller.rb

@@ -66,18 +66,13 @@ module Organizations
 
     def respond_invitation_acceptance_failure(failure)
       case failure.failure_reason
-      when :email_mismatch
-        return respond_invitation_email_mismatch
-      when :invitation_expired
-        return respond_invitation_expired
+      when :email_mismatch then respond_invitation_email_mismatch
+      when :invitation_expired then respond_invitation_expired
+      when :invitation_changed then respond_invitation_changed(failure.invitation || @invitation)
+      else
+        respond_invitation_error(html_path: main_app.root_path, alert: "Unable to accept this invitation.",
+                                 json_error: "Acceptance failed", status: 422)
       end
-
-      respond_invitation_error(
-        html_path: main_app.root_path,
-        alert: "Unable to accept this invitation.",
-        json_error: "Acceptance failed",
-        status: 422
-      )
     end
 
     def respond_invitation_email_mismatch
@@ -98,6 +93,14 @@ module Organizations
       )
     end
 
+    # A reissue changed the invitation during the acceptance, and nothing was
+    # written. Send the person back to it (its current link) to try again.
+    def respond_invitation_changed(invitation)
+      message = Organizations.t(:"errors.invitation_changed", organization: invitation.organization)
+      respond_invitation_error(html_path: invitation_path(invitation.token), alert: message, json_error: message,
+                               status: 409)
+    end
+
     def respond_invitation_acceptance_success(result)
       after_path = redirect_path_after_invitation_accepted(result.invitation, user: current_user)
       payload, status = invitation_acceptance_json_response(result)

data/config/locales/en.yml

@@ -72,6 +72,7 @@ en:
       # — Invitations —
       invitation_expired: "This invitation has expired"
       invitation_already_accepted: "This invitation has already been accepted"
+      invitation_changed: "This invitation changed while it was being accepted. Try again."
       invitation_cannot_resend_accepted: "Cannot resend an accepted invitation"
       invitation_email_mismatch: "This invitation was sent to a different email address"
       invitation_accept_as_owner: "Cannot accept invitation as owner. Invite as admin, then use transfer_ownership_to! after joining."
@@ -114,6 +115,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

@@ -54,6 +54,7 @@ es:
 
       invitation_expired: "Esta invitación ha caducado"
       invitation_already_accepted: "Esta invitación ya ha sido aceptada"
+      invitation_changed: "Esta invitación cambió mientras se aceptaba. Inténtalo de nuevo."
       invitation_cannot_resend_accepted: "No se puede reenviar una invitación ya aceptada"
       invitation_email_mismatch: "Esta invitación se envió a otra dirección de email"
       invitation_accept_as_owner: "No se puede aceptar una invitación como propietario. Invita como administrador y transfiere la propiedad después."
@@ -94,6 +95,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/controller_helpers.rb

@@ -290,6 +290,14 @@ module Organizations
           return_failure: return_failure,
           invitation: invitation
         )
+      rescue Organizations::Invitation::InvitationChanged
+        # A reissue changed the invitation at each try to lock it. Nothing
+        # was written, and the person can try again: keep the session token.
+        return invitation_acceptance_failure(
+          :invitation_changed,
+          return_failure: return_failure,
+          invitation: invitation
+        )
       rescue Organizations::InvitationAlreadyAccepted
         # Check if user is actually a member
         membership = Organizations::Membership.find_by(

data/lib/organizations/invitation_acceptance_failure.rb

@@ -10,6 +10,7 @@ module Organizations
       invitation_expired
       email_mismatch
       already_accepted_without_membership
+      invitation_changed
     ].freeze
 
     attr_reader :reason, :invitation

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/invitation.rb

@@ -124,6 +124,12 @@ module Organizations
     # Error raised when trying to accept an invitation with owner role
     class CannotAcceptAsOwner < Organizations::InvitationError; end
 
+    # The invitation named another inviter at each of ACCEPT_LOCK_ATTEMPTS
+    # tries to lock its rows (it was reissued meanwhile).
+    class InvitationChanged < Organizations::InvitationError; end
+
+    ACCEPT_LOCK_ATTEMPTS = 3
+
     # Accept the invitation and create membership
     # Uses row-level locking to prevent race conditions
     # @param user [User, nil] The user accepting (uses Current.user if not provided)
@@ -149,8 +155,7 @@ module Organizations
       membership = nil
 
       ActiveRecord::Base.transaction do
-        # Lock the invitation row to prevent race conditions
-        lock!
+        lock_rows_for_acceptance!(accepting_user)
 
         # Re-check status after acquiring lock
         if accepted?
@@ -231,6 +236,10 @@ module Organizations
     # @raise [Organizations::NotAuthorized] if the role ranks above revoked_by's own
     def revoke!(revoked_by: nil)
       ActiveRecord::Base.transaction do
+        # The organization row first (RowLocks), as an organization destroy
+        # and the inviter's deletion lock it before this invitation and its
+        # grants.
+        RowLocks.lock_organization!(organization_id)
         lock!
         authorize_management!(revoked_by)
         destroy!
@@ -257,6 +266,31 @@ module Organizations
 
     private
 
+    # The gem's lock order (RowLocks): the users that the membership names
+    # (the accepting user and the inviter), then the organization row, then
+    # the invitation row. A deletion of the inviter or of the organization
+    # takes the same order, so it waits for this acceptance, or this one for
+    # it. This copy can name a stale inviter: a reissue of the expired row
+    # (send_invite_to!) names the new one. The row lock reads the row again.
+    # When it names other ids than the ones locked, the savepoint rolls back,
+    # which releases its locks, and the next attempt locks the current ids.
+    def lock_rows_for_acceptance!(accepting_user)
+      ACCEPT_LOCK_ATTEMPTS.times do
+        locked = [invited_by_id, organization_id]
+        held = ActiveRecord::Base.transaction(requires_new: true) do
+          RowLocks.lock_users!(accepting_user.id, invited_by_id)
+          RowLocks.lock_organization!(organization_id)
+          lock!
+          raise ActiveRecord::Rollback unless [invited_by_id, organization_id] == locked
+
+          true
+        end
+        return if held
+      end
+
+      raise InvitationChanged, Organizations.t(:"errors.invitation_changed", organization: organization)
+    end
+
     # The invitation's grants become the membership's (a grant on the same
     # resource takes the invitation's capabilities). The inviter was
     # checked when the invitation was sent.

data/lib/organizations/models/join_code.rb

@@ -152,10 +152,7 @@ module Organizations
       outcome = nil
 
       ActiveRecord::Base.transaction do
-        # Lock the code row: uses_count accounting and the max_uses cap must
-        # be race-safe (two concurrent redemptions of a max_uses: 1 code must
-        # yield exactly one success).
-        lock!
+        lock_rows_for_redemption!(user)
         ensure_redeemable!
 
         # Already a member — idempotent no-op that does NOT consume a use.
@@ -188,6 +185,18 @@ module Organizations
 
     private
 
+    # The gem's lock order (RowLocks): the redeeming user, then the
+    # organization row, then the code row. The deletion of the code's
+    # creator and an organization destroy take the organization row before
+    # the code row. The code row lock makes the uses_count accounting and
+    # the max_uses cap race-safe (two concurrent redemptions of a max_uses: 1
+    # code must yield exactly one success).
+    def lock_rows_for_redemption!(user)
+      RowLocks.lock_users!(user.id)
+      RowLocks.lock_organization!(organization_id)
+      lock!
+    end
+
     def ensure_redeemable!
       raise JoinCodeInvalid, Organizations.t(:"errors.join_code_invalid") if revoked? || expired?
       raise JoinCodeExhausted, Organizations.t(:"errors.join_code_exhausted") if exhausted?

data/lib/organizations/models/join_request.rb

@@ -180,7 +180,7 @@ module Organizations
       failure = nil
 
       ActiveRecord::Base.transaction do
-        lock!
+        lock_rows_for_verification!
         ensure_open!
         ensure_active_challenge!
         # The domain or roster entry may have been removed, revoked or
@@ -319,11 +319,30 @@ module Organizations
 
     private
 
+    # The gem's lock order (RowLocks): the requester, then the organization
+    # row, then this request. An organization destroy deletes the domains
+    # and allowlist entries before this request, and the check locks one of
+    # them after this request. The automatic approval takes the requester's
+    # guard again: inside a host transaction, this one already holds it, so
+    # the approval does not ask for a user row while it holds the
+    # organization row.
+    def lock_rows_for_verification!
+      RowLocks.lock_users!(user_id)
+      RowLocks.lock_organization!(organization_id)
+      lock!
+    end
+
     def perform_approval!(decided_by:, recheck_instruments:)
       membership = nil
       reused_existing = false
 
       ActiveRecord::Base.transaction do
+        # The gem's lock order (RowLocks): the requester and the decider,
+        # then the organization row, then this request. The requester's
+        # deletion locks the requester, then the organization, and deletes
+        # this request.
+        RowLocks.lock_users!(user_id, decided_by&.id)
+        RowLocks.lock_organization!(organization_id)
         lock!
 
         return approved_membership! if approved? # idempotent re-approval

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/row_locks.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Organizations
+  # The one lock order of the gem: the user rows (in id order), then the
+  # organization row, then the rows of the organization. A user's deletion
+  # locks the user row, then the row of every organization in which it
+  # writes. An organization's destroy locks its row before its cascades. A
+  # path that writes in an organization takes the same order, or it can
+  # deadlock with them on PostgreSQL.
+  #
+  # The user rows are the ones that the path's writes reference: a row that
+  # names a user takes a key share lock on it when it is written, which
+  # waits for a deletion of that user. Lock them first, so that the wait
+  # comes before the organization row and not after it.
+  #
+  # The user guard is a key share lock (FOR KEY SHARE on PostgreSQL). It
+  # conflicts with the deletion's FOR UPDATE, which is its purpose, and with
+  # nothing else: an ordinary update of the user and the foreign key check
+  # of another writer pass. A FOR UPDATE guard would block those writers,
+  # and a writer that holds a row this path waits for would then close a
+  # cycle (a reject! that sets decided_by_id, a grant that names its
+  # granter).
+  #
+  # Inside a host transaction the order holds only when the host's earlier
+  # locks in that transaction keep it too.
+  #
+  # @api private
+  module RowLocks
+    module_function
+
+    # Take the key share guard on these users' rows, in id order. Nil ids
+    # and users that are gone are skipped.
+    # @param ids [Array<Object>]
+    def lock_users!(*ids)
+      ids = ids.flatten.compact.uniq
+      return if ids.empty?
+
+      user_class = Organizations.user_class
+      key = user_class.primary_key
+      user_class.unscoped.where(key => ids).order(key).lock(key_share_clause(user_class.connection)).pluck(key)
+    end
+
+    # PostgreSQL has a lock that only a delete or a key change conflicts
+    # with. MySQL has a shared lock. SQLite has no row locks: Rails drops
+    # the clause there.
+    def key_share_clause(connection)
+      adapter = connection.adapter_name.downcase
+      return "FOR KEY SHARE" if adapter.include?("postg")
+      return "LOCK IN SHARE MODE" if adapter.include?("mysql") || adapter.include?("trilogy")
+
+      true
+    end
+
+    # Lock the organization row. A destroyed organization is skipped: the
+    # caller's own row lock then finds its row gone.
+    # @param id [Object]
+    def lock_organization!(id)
+      Organizations::Organization.unscoped.where(id: id).lock.pick(:id)
+    end
+  end
+end

data/lib/organizations/version.rb

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

data/lib/organizations.rb

@@ -126,6 +126,7 @@ module Organizations
   autoload :GrantAccess, "organizations/grant_access"
   autoload :Grantable, "organizations/grantable"
   autoload :AccountDeletionPlan, "organizations/account_deletion_plan"
+  autoload :RowLocks, "organizations/row_locks"
 
   # Alias for README compatibility: `include Organizations::Controller`
   Controller = ControllerHelpers

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: organizations
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -180,6 +180,7 @@ files:
 - lib/organizations/public_email_domains.rb
 - lib/organizations/resource.rb
 - lib/organizations/roles.rb
+- lib/organizations/row_locks.rb
 - lib/organizations/test_helpers.rb
 - lib/organizations/version.rb
 - lib/organizations/view_helpers.rb