Implement guarded prepared local retry transactions

.github/pr-test-selection.json

@@ -20,7 +20,11 @@
     "tests/Unit/V2/LaravelDependencySecurityPolicyTest.php",
     "tests/Unit/V2/PlatformProtocolSpecsTest.php",
     "tests/Unit/V2/PreparedLocalActivityReportTest.php",
+    "tests/Unit/V2/PreparedLocalActivityRetryTaskBridgeTest.php",
+    "tests/Unit/V2/PreparedLocalRetryDecisionTest.php",
+    "tests/Unit/V2/PreparedLocalRetryDescriptorTest.php",
     "tests/Unit/V2/PreparedLocalRetryPolicyTest.php",
+    "tests/Unit/V2/PreparedLocalRetryTimestampTest.php",
     "tests/Unit/V2/ReadmeBranchDestinationsTest.php",
     "tests/Unit/V2/ScopedCancellationContextTest.php",
     "tests/Unit/V2/SqliteTransactionTest.php",

src/V2/Contracts/PreparedLocalActivityRetryTaskBridge.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Workflow\V2\Contracts;
+
+use Workflow\V2\Support\WorkerProtocolVersion;
+
+/**
+ * @internal Optional prepared-local retry contract 2. This declaration binds
+ * no implementation. Consumers must inspect the actual bridge instance and
+ * retain original claim capability, contract 2 and snapshot 2 authority.
+ * The type alone grants neither local mode nor physical callback admission.
+ */
+interface PreparedLocalActivityRetryTaskBridge extends PreparedLocalActivityTaskBridge
+{
+    /** @param array<string, mixed> $descriptor
+     * @return array<string, mixed>
+     */
+    public function prepareLocalActivityWithRetryPolicy(
+        string $taskId,
+        string $leaseOwner,
+        int $workflowTaskAttempt,
+        int $sequence,
+        string $workerAttemptId,
+        array $descriptor,
+        string $protocolVersion = WorkerProtocolVersion::VERSION,
+    ): array;
+
+    /** @param array<string, mixed> $report
+     * @return array<string, mixed>
+     */
+    public function recordLocalActivityRetryOutcome(
+        string $attemptId,
+        string $leaseOwner,
+        int $workflowTaskAttempt,
+        array $report,
+        string $protocolVersion = WorkerProtocolVersion::VERSION,
+    ): array;
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function controlLocalActivityWithRetryPolicy(
+        string $attemptId,
+        string $leaseOwner,
+        int $workflowTaskAttempt,
+        bool $renewLease = false,
+        string $protocolVersion = WorkerProtocolVersion::VERSION,
+    ): array;
+
+    /** @param array<string, mixed> $progress
+     * @return array<string, mixed>
+     */
+    public function heartbeatLocalActivityWithRetryPolicy(
+        string $attemptId,
+        string $leaseOwner,
+        int $workflowTaskAttempt,
+        array $progress = [],
+        string $protocolVersion = WorkerProtocolVersion::VERSION,
+    ): array;
+
+    /** @param array<string, mixed> $descriptor
+     * @return array<string, mixed>
+     */
+    public function recoverLocalActivityWithRetryPolicy(
+        string $taskId,
+        string $leaseOwner,
+        int $workflowTaskAttempt,
+        int $sequence,
+        array $descriptor,
+        string $protocolVersion = WorkerProtocolVersion::VERSION,
+    ): array;
+}

src/V2/Exceptions/PreparedLocalActivityContractException.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Workflow\V2\Exceptions;
+
+use RuntimeException;
+
+/** @internal A prepared activity entered through a different contract. */
+final class PreparedLocalActivityContractException extends RuntimeException
+{
+}

src/V2/Support/HistoryEventPayloadContract.php

@@ -200,6 +200,7 @@ final class HistoryEventPayloadContract
         ],
         'ActivityRetryScheduled' => [
             'local_outcome',
+            'retry_disposition',
             'local_recovery',
             'activity_execution_id',
             'activity_attempt_id',
@@ -266,6 +267,7 @@ final class HistoryEventPayloadContract
         ],
         'ActivityFailed' => [
             'local_outcome',
+            'retry_disposition',
             'local_recovery',
             'activity_execution_id',
             'activity_attempt_id',
@@ -345,6 +347,7 @@ final class HistoryEventPayloadContract
         ],
         'ActivityTimedOut' => [
             'local_outcome',
+            'retry_disposition',
             'local_recovery',
             'activity_execution_id',
             'activity_attempt_id',