|
| 1 | +<?php |
| 2 | + |
| 3 | +namespace Waterline\Tests\Unit\Support; |
| 4 | + |
| 5 | +use PHPUnit\Framework\TestCase; |
| 6 | +use Waterline\Support\RunDiagnostics; |
| 7 | + |
| 8 | +/** |
| 9 | + * Pins Waterline operator-facing run diagnostics to the v2 execution-semantics |
| 10 | + * and idempotency contract frozen in the workflow package at |
| 11 | + * docs/architecture/execution-guarantees.md. |
| 12 | + * |
| 13 | + * The contract is the single reference for duplicate-execution, retry, lease |
| 14 | + * expiry, and redelivery semantics across product docs, CLI reasoning, |
| 15 | + * Waterline diagnostics, and test coverage. When the contract renames or |
| 16 | + * narrows a guarantee, the {@see RunDiagnostics::GUIDANCE} strings and this |
| 17 | + * pinning test must be updated in the same change so operator vocabulary does |
| 18 | + * not drift away from the contract silently. |
| 19 | + * |
| 20 | + * Required reading before changing this test: |
| 21 | + * - workflow package: docs/architecture/execution-guarantees.md |
| 22 | + * - workflow package: tests/Unit/V2/ExecutionGuaranteesDocumentationTest.php |
| 23 | + */ |
| 24 | +final class V2DiagnosticsExecutionContractAlignmentTest extends TestCase |
| 25 | +{ |
| 26 | + /** |
| 27 | + * Every diagnostic code Waterline's RunDiagnostics can emit must carry |
| 28 | + * contract-aligned operator guidance. Adding a new diagnostic that has no |
| 29 | + * guidance string is a pinning failure; either add guidance or explicitly |
| 30 | + * map the code to null in {@see RunDiagnostics::GUIDANCE} if the |
| 31 | + * diagnostic is not a semantics teaching moment. |
| 32 | + */ |
| 33 | + public function testEveryKnownDiagnosticCodeHasGuidance(): void |
| 34 | + { |
| 35 | + $expected = [ |
| 36 | + 'activity_repeated_failure', |
| 37 | + 'activity_heartbeat_timeout_not_effective', |
| 38 | + 'activity_unbounded_retry_policy', |
| 39 | + 'workflow_task_repeated_failure', |
| 40 | + 'history_budget_near_limit', |
| 41 | + 'condition_wait_stuck', |
| 42 | + ]; |
| 43 | + |
| 44 | + foreach ($expected as $code) { |
| 45 | + $this->assertArrayHasKey( |
| 46 | + $code, |
| 47 | + RunDiagnostics::GUIDANCE, |
| 48 | + sprintf('RunDiagnostics::GUIDANCE is missing contract guidance for code %s.', $code), |
| 49 | + ); |
| 50 | + $this->assertNotEmpty( |
| 51 | + RunDiagnostics::GUIDANCE[$code], |
| 52 | + sprintf('Contract guidance for %s must be a non-empty string.', $code), |
| 53 | + ); |
| 54 | + } |
| 55 | + } |
| 56 | + |
| 57 | + /** |
| 58 | + * Duplicate execution is a first-class distributed reality in the v2 |
| 59 | + * contract, not a bug condition. Activity-retry guidance must describe |
| 60 | + * retries as at-least-once and direct the operator to the |
| 61 | + * activity_execution_id idempotency surface, which is the default |
| 62 | + * framework-provided idempotency key that stays stable across retries. |
| 63 | + */ |
| 64 | + public function testActivityRetryGuidanceCitesAtLeastOnceAndExecutionIdSurface(): void |
| 65 | + { |
| 66 | + $guidance = RunDiagnostics::GUIDANCE['activity_repeated_failure']; |
| 67 | + |
| 68 | + $this->assertStringContainsString('at-least-once', $guidance); |
| 69 | + $this->assertStringContainsString('activity_execution_id', $guidance); |
| 70 | + $this->assertStringContainsString('idempotency', $guidance); |
| 71 | + } |
| 72 | + |
| 73 | + /** |
| 74 | + * The heartbeat-timeout diagnostic must explain that heartbeats renew the |
| 75 | + * activity attempt lease, and that a start_to_close timeout that fires |
| 76 | + * first prevents lease expiry from triggering redelivery. The contract |
| 77 | + * language for this surface is "lease" plus the concrete timeout fields. |
| 78 | + */ |
| 79 | + public function testHeartbeatTimeoutGuidanceCitesLeaseAndTimeoutFields(): void |
| 80 | + { |
| 81 | + $guidance = RunDiagnostics::GUIDANCE['activity_heartbeat_timeout_not_effective']; |
| 82 | + |
| 83 | + $this->assertStringContainsString('Heartbeat', $guidance); |
| 84 | + $this->assertStringContainsString('lease', $guidance); |
| 85 | + $this->assertStringContainsString('start_to_close_timeout', $guidance); |
| 86 | + $this->assertStringContainsString('heartbeat_timeout', $guidance); |
| 87 | + } |
| 88 | + |
| 89 | + /** |
| 90 | + * Unbounded retry policies keep producing new attempts for the same |
| 91 | + * activity_execution_id. Contract guidance names at-least-once and the |
| 92 | + * execution-id surface so operators can reason about the dedupe key the |
| 93 | + * retries share. |
| 94 | + */ |
| 95 | + public function testUnboundedRetryGuidanceCitesAtLeastOnceAndExecutionIdSurface(): void |
| 96 | + { |
| 97 | + $guidance = RunDiagnostics::GUIDANCE['activity_unbounded_retry_policy']; |
| 98 | + |
| 99 | + $this->assertStringContainsString('at-least-once', $guidance); |
| 100 | + $this->assertStringContainsString('activity_execution_id', $guidance); |
| 101 | + $this->assertStringContainsString('max_attempts', $guidance); |
| 102 | + } |
| 103 | + |
| 104 | + /** |
| 105 | + * Workflow-task failures are never duplicate application execution — the |
| 106 | + * workflow body is replayed deterministically. Contract guidance must |
| 107 | + * separate workflow-task replay from activity at-least-once so operators |
| 108 | + * stop reading repeated workflow-task failures as duplicate side effects. |
| 109 | + */ |
| 110 | + public function testWorkflowTaskGuidanceCitesDeterministicReplay(): void |
| 111 | + { |
| 112 | + $guidance = RunDiagnostics::GUIDANCE['workflow_task_repeated_failure']; |
| 113 | + |
| 114 | + $this->assertStringContainsString('replay', $guidance); |
| 115 | + $this->assertStringContainsString('deterministic', $guidance); |
| 116 | + $this->assertStringContainsString('side effect', $guidance); |
| 117 | + } |
| 118 | + |
| 119 | + /** |
| 120 | + * The history budget diagnostic must point operators at continue-as-new |
| 121 | + * as a new-run primitive, not at history truncation. The contract is |
| 122 | + * explicit that the durable history rows are exactly-once at the durable |
| 123 | + * state layer. |
| 124 | + */ |
| 125 | + public function testHistoryBudgetGuidanceCitesContinueAsNewAndDurableHistory(): void |
| 126 | + { |
| 127 | + $guidance = RunDiagnostics::GUIDANCE['history_budget_near_limit']; |
| 128 | + |
| 129 | + $this->assertStringContainsString('Continue-as-new', $guidance); |
| 130 | + $this->assertStringContainsString('workflow_run_id', $guidance); |
| 131 | + $this->assertStringContainsString('workflow_instance_id', $guidance); |
| 132 | + $this->assertStringContainsString('exactly-once', $guidance); |
| 133 | + } |
| 134 | + |
| 135 | + /** |
| 136 | + * Condition waits block the run on a durable resume source. Contract |
| 137 | + * guidance names the resume sources an operator should look for so the |
| 138 | + * "stuck" state reads as a missing signal/update/timer rather than a |
| 139 | + * framework bug. |
| 140 | + */ |
| 141 | + public function testConditionWaitGuidanceCitesResumeSources(): void |
| 142 | + { |
| 143 | + $guidance = RunDiagnostics::GUIDANCE['condition_wait_stuck']; |
| 144 | + |
| 145 | + $this->assertStringContainsString('durable', $guidance); |
| 146 | + $this->assertStringContainsString('signal', $guidance); |
| 147 | + $this->assertStringContainsString('update', $guidance); |
| 148 | + } |
| 149 | + |
| 150 | + /** |
| 151 | + * Guidance strings are reviewed as part of the contract. Every guidance |
| 152 | + * entry must stay short (single paragraph) so it fits next to the |
| 153 | + * diagnostic in operator tooling. |
| 154 | + */ |
| 155 | + public function testGuidanceStringsAreConciseSingleParagraphs(): void |
| 156 | + { |
| 157 | + foreach (RunDiagnostics::GUIDANCE as $code => $guidance) { |
| 158 | + $this->assertIsString($guidance, sprintf('Guidance for %s must be a string.', $code)); |
| 159 | + $this->assertLessThanOrEqual( |
| 160 | + 400, |
| 161 | + strlen($guidance), |
| 162 | + sprintf('Guidance for %s is longer than 400 characters; keep it concise.', $code), |
| 163 | + ); |
| 164 | + $this->assertStringNotContainsString( |
| 165 | + "\n\n", |
| 166 | + $guidance, |
| 167 | + sprintf('Guidance for %s must be a single paragraph with no blank lines.', $code), |
| 168 | + ); |
| 169 | + } |
| 170 | + } |
| 171 | +} |
0 commit comments