package_manager WIP

package_manager/src/Event/PostDestroyEvent.php

@@ -4,6 +4,11 @@ namespace Drupal\package_manager\Event;
 
 /**
  * Event fired after the staging area is destroyed.
+ *
+ * If the stage is being force destroyed ::getStage() may return an instance of
+ * Stage that is different from the instance that created the stage.
+ *
+ * @see \Drupal\package_manager\Stage::destroy()
  */
 class PostDestroyEvent extends StageEvent {
 }

package_manager/src/Event/PreDestroyEvent.php

@@ -4,6 +4,11 @@ namespace Drupal\package_manager\Event;
 
 /**
  * Event fired before the staging area is destroyed.
+ *
+ * If the stage is being force destroyed ::getStage() may return an instance of
+ * Stage that is different from the instance that created the stage.
+ *
+ * @see \Drupal\package_manager\Stage::destroy()
  */
 class PreDestroyEvent extends PreOperationStageEvent {
 }

package_manager/src/Stage.php

@@ -407,12 +407,16 @@ class Stage {
   }
 
   /**
-   * Ensures that the current user or session owns the staging area.
+   * Validates the ownership of staging area.
+   *
+   * The stage is considered under valid ownership if it was created by current
+   * user or session, using the current class.
    *
    * @throws \LogicException
    *   If ::claim() has not been previously called.
    * @throws \Drupal\package_manager\Exception\StageOwnershipException
-   *   If the current user or session does not own the staging area.
+   *   If the current user or session does not own the staging area, or it was
+   *   created by a different class.
    */
   final protected function checkOwnership(): void {
     if (empty($this->lock)) {