From 698589edbdc6f44d142ed35d8044045775d3d430 Mon Sep 17 00:00:00 2001
From: lukinovec <lukinovec@gmail.com>
Date: Fri, 12 Jun 2026 11:47:39 +0200
Subject: [PATCH] Add comments for clarity (re-fetching and event firing)

---
 src/Database/Concerns/HasPending.php | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/Database/Concerns/HasPending.php b/src/Database/Concerns/HasPending.php
index f0d2ea0e..922c6bdf 100644
--- a/src/Database/Concerns/HasPending.php
+++ b/src/Database/Concerns/HasPending.php
@@ -111,6 +111,9 @@ trait HasPending
                 return $firstOrCreate ? static::create($attributes) : null;
             }
 
+            // Fired before the claim, so it can fire once per attempt, including for a candidate
+            // that ends up being claimed by a concurrent process (in which case the loop retries).
+            // PendingTenantPulled (below) fires exactly once, for the pulled tenant.
             event(new PullingPendingTenant($pullCandidate));
 
             $tenant = DB::transaction(function () use ($pullCandidate, $attributes): ?Tenant {
@@ -122,6 +125,8 @@ trait HasPending
                     return null;
                 }
 
+                // The tenant's pending_since was just cleared, and e.g. a PullingPendingTenant listener
+                // may have made changes to the tenant, so re-fetch it to get it in the correct state.
                 /** @var Model&Tenant $pulledTenant */
                 $pulledTenant = static::findOrFail($pullCandidate->getKey());