Stop PersistentActor by default when RecoveryCompleted handler fails

[He-Pin]

Motivation

A classic PersistentActor can enter an unbounded restart loop when its RecoveryCompleted handler throws because the Classic default decider restarts ordinary exceptions. Issues #3234 and #3249 describe the same trigger and root cause.

RecoveryCompleted runs after event replay has succeeded, so this failure should remain visible to the parent supervisor instead of being translated into an onRecoveryFailure replay failure.

Modification

• Wrap NonFatal exceptions from the RecoveryCompleted handler in ActorInitializationException and pass them to Classic supervision.
• Preserve the existing processing-state transition and outer recovery-permit cleanup path.
• Add directional regression coverage for both the default Stop decision and a custom parent Restart decision.
• Document the resulting supervision contract.

Result

The default supervision strategy stops the actor instead of repeatedly restarting it. A custom parent strategy can still Resume or Restart the same ActorRef, and the original exception is retained as the cause.

Tests

• sbt "persistence / Test / testOnly org.apache.pekko.persistence.RecoveryPermitterSpec" — restart-direction test failed before the production change; 7 passed after it
• sbt "persistence / Test / test" — 62 passed
• sbt docs/paradox — passed with existing duplicate-anchor warnings
• sbt headerCreateAll — passed
• sbt +headerCheckAll — passed for Scala 2.13.18 and 3.3.8
• sbt checkCodeStyle — passed
• sbt validatePullRequest — ran for 24m44s; affected persistence, typed, query, cluster-sharding, multi-JVM, and docs tests completed. Overall exit 1 is limited to unchanged baseline/environment failures: LeveldbJournalNativeSpec cannot load the x86 leveldbjni-all 1.8 binary on macOS ARM64, and IntegrationDocTest references the existing invalid class pekko.dispatch.UnboundedMailbox
• sbt sortImports — not completed because the repository Scalafix rule fails against the current scala.meta with NoSuchMethodError; no unrelated changes were retained
• scalafmt --list --mode diff-ref=origin/main — passed
• git diff --check — passed
• Qoder stdout review — No must-fix findings

References

Fixes #3234
Fixes #3249

[pjfanning]

lgtm