diff --git a/.changeset/positional-pop-to-fixtures.md b/.changeset/positional-pop-to-fixtures.md
index f0f47cf35..c3b1272f8 100644
--- a/.changeset/positional-pop-to-fixtures.md
+++ b/.changeset/positional-pop-to-fixtures.md
@@ -1,5 +1,5 @@
 ---
-'@rundown-org/core': patch
+'@rundown-org/core': major
 ---
 
 # Move the positional pop out of product reach
diff --git a/packages/core/src/runbook/session-service.ts b/packages/core/src/runbook/session-service.ts
index 136b51a8f..04a8849ad 100644
--- a/packages/core/src/runbook/session-service.ts
+++ b/packages/core/src/runbook/session-service.ts
@@ -1953,9 +1953,11 @@ export class SessionService {
   /**
    * Release a runbook from an in-memory session (no IO, no transaction).
    *
-   * Pure in-place mutation so composite operations — {@link releaseRunbooks},
-   * {@link popRunbookIfActive} — can release several runbooks against one
-   * session snapshot and commit once, instead of round-tripping per runbook.
+   * Pure in-place mutation so a caller can release against a session snapshot
+   * it already holds and commit once, instead of round-tripping per release.
+   * {@link releaseRunbooks} needs that to put several runbooks under a single
+   * commit; {@link popRunbookIfActive} releases exactly one, folded into the
+   * same transaction that decides whether the run is still the top.
    *
    * @param session - Session to mutate in place.
    * @param runbookId - Runbook id to release from session targeting structures
diff --git a/packages/core/src/testing/session-fixtures.ts b/packages/core/src/testing/session-fixtures.ts
index f9e07fab9..517bed18f 100644
--- a/packages/core/src/testing/session-fixtures.ts
+++ b/packages/core/src/testing/session-fixtures.ts
@@ -308,10 +308,11 @@ export async function stashRunbookUnverified(
  * @param manager - State manager whose store holds the runs and the session;
  *   take the caller's own instance so the fixture shares one store with the
  *   test.
- * @returns The new top-of-stack run id, or null when the stack was empty or the
- *   release removed nothing. Refused `execution_in_progress` or
- *   `recovery_required` instead when the popped run is execution-owned or
- *   awaiting recovery; the value is absent then.
+ * @returns The new top-of-stack run id, or null when no run remains on the
+ *   stack — either because it was already empty and nothing was released, or
+ *   because the run just popped was the last entry. Refused
+ *   `execution_in_progress` or `recovery_required` instead when the popped run
+ *   is execution-owned or awaiting recovery; the value is absent then.
  */
 export async function popTopOfStackUnverified(
   manager: RunbookStateManager,