Relax workflow cache admission to warning-only diagnostics

durable-workflow-ops · durable-workflow-ops · commit d1e2378dcd6e · 2026-04-28T12:34:33.000Z
Relax cache admission to warning-only diagnostics
diff --git a/src/V2/Support/BackendCapabilities.php b/src/V2/Support/BackendCapabilities.php
@@ -175,16 +175,19 @@ private static function cache(?string $configuredStore = null): array
         if ($store === null || $driver === null) {
             $issues[] = self::issue(
                 'cache',
-                'error',
+                'warning',
                 'cache_store_missing',
-                'Workflow v2 requires a configured cache store for worker-loop throttles and compatibility heartbeat fallbacks.',
+                'No cache store is configured. Wake acceleration, repair-loop throttles, and cache-backed fleet fallbacks may be degraded, but durable dispatch remains correct.',
             );
         } elseif (! $lockSupported) {
             $issues[] = self::issue(
                 'cache',
-                'error',
+                'warning',
                 'cache_locks_unsupported',
-                sprintf('The [%s] cache store does not advertise Laravel atomic lock support.', $store),
+                sprintf(
+                    'The [%s] cache store does not advertise Laravel atomic lock support. Wake acceleration remains optional, but repair-loop throttles and cache-backed fleet fallbacks may be degraded.',
+                    $store,
+                ),
             );
         }
 
diff --git a/src/V2/Support/HealthCheck.php b/src/V2/Support/HealthCheck.php
@@ -66,15 +66,23 @@ private static function backendCheck(array $backend): array
     {
         $issues = is_array($backend['issues'] ?? null) ? $backend['issues'] : [];
         $supported = BackendCapabilities::isSupported($backend);
+        $severity = is_string($backend['severity'] ?? null) ? $backend['severity'] : ($supported ? 'ok' : 'error');
 
         return self::check(
             'backend_capabilities',
-            $supported ? 'ok' : 'error',
-            $supported
-                ? 'The configured database, queue, and cache backends satisfy the v2 capability contract.'
-                : 'One or more configured v2 backend capabilities are unsupported.',
+            match ($severity) {
+                'error' => 'error',
+                'warning' => 'warning',
+                default => 'ok',
+            },
+            match ($severity) {
+                'error' => 'One or more configured v2 backend capabilities are unsupported.',
+                'warning' => 'One or more configured v2 backend capabilities are degraded but non-blocking.',
+                default => 'The configured database, queue, cache, and codec backends satisfy the v2 capability contract.',
+            },
             self::CATEGORY_CORRECTNESS,
             [
+                'severity' => $severity,
                 'issue_count' => count($issues),
                 'issues' => $issues,
             ],
diff --git a/src/V2/Support/LongPollCacheValidator.php b/src/V2/Support/LongPollCacheValidator.php
@@ -10,11 +10,11 @@
 use Illuminate\Support\Str;
 
 /**
- * Validates cache backend configuration for long-poll coordination in multi-node deployments.
+ * Validates cache backend configuration for long-poll wake acceleration in multi-node deployments.
  *
- * Multi-node deployments require shared cache backends (Redis, database, Memcached)
- * for wake signal propagation. File-based cache is per-node and cannot coordinate
- * across nodes.
+ * Shared cache backends (Redis, database, Memcached) are required only for
+ * cross-node wake propagation. Durable dispatch correctness does not depend on
+ * this layer, but latency and rollout-safety diagnostics do.
  *
  * @see \Workflow\V2\Contracts\LongPollWakeStore
  */
@@ -53,7 +53,7 @@ public function validateMultiNodeCapable(CacheRepository $cache): array
     }
 
     /**
-     * Check if current configuration is safe for multi-node deployment.
+     * Check if current configuration is safe for multi-node wake acceleration.
      *
      * @return array{
      *     safe: bool,
@@ -82,7 +82,7 @@ public function checkMultiNodeSafety(CacheRepository $cache, bool $multiNode): a
         return [
             'safe' => false,
             'message' => sprintf(
-                'Multi-node deployment detected (DW_V2_MULTI_NODE=true) but cache backend is "%s". %s',
+                'Multi-node wake acceleration is enabled (DW_V2_MULTI_NODE=true) but cache backend is "%s". %s',
                 $validation['backend'],
                 $validation['reason']
             ),
diff --git a/src/V2/Support/ReadinessContract.php b/src/V2/Support/ReadinessContract.php
@@ -67,7 +67,7 @@ public static function definition(): array
                 'dispatch' => [
                     'authority' => BackendCapabilities::class . '::snapshot',
                     'readiness_key' => 'supported',
-                    'gate' => 'No database, queue, cache, codec, or structural-limit issue has error severity.',
+                    'gate' => 'No database, queue, codec, or structural-limit issue has error severity; cache issues remain non-blocking warnings.',
                     'unready_behavior' => 'Task dispatch does not claim unsupported durable work; operators see backend_capabilities errors.',
                 ],
                 'claim' => [
@@ -107,6 +107,8 @@ public static function definition(): array
                 ],
                 'cache' => [
                     'required_capabilities' => ['atomic_locks'],
+                    'dispatch_blocking_severity' => 'warning',
+                    'role' => 'acceleration_only',
                 ],
                 'codec' => [
                     'default_for_new_v2_runs' => 'avro',
@@ -130,7 +132,7 @@ public static function forBackendCapabilities(): array
         $contract['effective_states'] = [
             'dispatch' => [
                 'state' => 'evaluated_by_backend_capabilities_snapshot',
-                'blocking_rule' => 'Any error-severity backend issue makes supported=false.',
+                'blocking_rule' => 'Any error-severity database, queue, codec, or structural-limit issue makes supported=false; cache diagnostics stay warning-only.',
             ],
             'claim' => [
                 'state' => 'evaluated_per_task_queue_connection',
diff --git a/tests/Support/NonLockingCacheStore.php b/tests/Support/NonLockingCacheStore.php
@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Support;
+
+use Illuminate\Contracts\Cache\Store;
+
+final class NonLockingCacheStore implements Store
+{
+    /**
+     * @var array<string, mixed>
+     */
+    private array $values = [];
+
+    public function get($key)
+    {
+        return $this->values[$key] ?? null;
+    }
+
+    public function many(array $keys): array
+    {
+        $values = [];
+
+        foreach ($keys as $key) {
+            $values[$key] = $this->get($key);
+        }
+
+        return $values;
+    }
+
+    public function put($key, $value, $seconds): bool
+    {
+        $this->values[$key] = $value;
+
+        return true;
+    }
+
+    public function putMany(array $values, $seconds): bool
+    {
+        foreach ($values as $key => $value) {
+            $this->put($key, $value, $seconds);
+        }
+
+        return true;
+    }
+
+    public function increment($key, $value = 1)
+    {
+        $current = (int) ($this->values[$key] ?? 0);
+        $current += $value;
+        $this->values[$key] = $current;
+
+        return $current;
+    }
+
+    public function decrement($key, $value = 1)
+    {
+        $current = (int) ($this->values[$key] ?? 0);
+        $current -= $value;
+        $this->values[$key] = $current;
+
+        return $current;
+    }
+
+    public function forever($key, $value): bool
+    {
+        return $this->put($key, $value, 0);
+    }
+
+    public function forget($key): bool
+    {
+        unset($this->values[$key]);
+
+        return true;
+    }
+
+    public function flush(): bool
+    {
+        $this->values = [];
+
+        return true;
+    }
+
+    public function getPrefix(): string
+    {
+        return 'test-non-locking:';
+    }
+}
diff --git a/tests/Unit/Commands/V2DoctorCommandTest.php b/tests/Unit/Commands/V2DoctorCommandTest.php
@@ -4,6 +4,9 @@
 
 namespace Tests\Unit\Commands;
 
+use Illuminate\Cache\CacheManager;
+use Illuminate\Cache\Repository;
+use Tests\Support\NonLockingCacheStore;
 use Tests\TestCase;
 
 final class V2DoctorCommandTest extends TestCase
@@ -119,4 +122,40 @@ public function testQueueModeSyncQueueIsReportedAsErrorAndFailsStrict(): void
             ->expectsOutputToContain('[ERROR] [queue_sync_unsupported]')
             ->assertFailed();
     }
+
+    public function testCustomNoLockCacheStoreAppearsInJsonOutputAndStrictStillSucceeds(): void
+    {
+        config()->set('queue.default', 'redis');
+        config()
+            ->set('queue.connections.redis.driver', 'redis');
+        config()
+            ->set('workflows.serializer', 'avro');
+        $this->configureNonLockingCacheStore();
+
+        $this->artisan('workflow:v2:doctor', [
+            '--json' => true,
+            '--strict' => true,
+        ])
+            ->expectsOutputToContain('"code":"cache_locks_unsupported"')
+            ->assertSuccessful();
+    }
+
+    private function configureNonLockingCacheStore(): void
+    {
+        $driver = 'test-non-locking';
+        $store = 'test-non-locking';
+
+        $this->app['cache']->extend($driver, function (): Repository {
+            if (! $this instanceof CacheManager) {
+                throw new \RuntimeException('Unexpected cache manager binding.');
+            }
+
+            return new Repository(new NonLockingCacheStore());
+        });
+
+        config()
+            ->set("cache.stores.{$store}.driver", $driver);
+        config()
+            ->set('cache.default', $store);
+    }
 }
diff --git a/tests/Unit/V2/BackendCapabilitiesTest.php b/tests/Unit/V2/BackendCapabilitiesTest.php
@@ -4,7 +4,10 @@
 
 namespace Tests\Unit\V2;
 
+use Illuminate\Cache\CacheManager;
+use Illuminate\Cache\Repository;
 use Illuminate\Support\Carbon;
+use Tests\Support\NonLockingCacheStore;
 use Tests\TestCase;
 use Workflow\V2\Support\BackendCapabilities;
 
@@ -93,11 +96,17 @@ public function testSnapshotIncludesFrozenReadinessContractMatrix(): void
             'info',
             $contract['backend_capabilities']['queue']['poll_mode']['sync_or_missing_queue_severity']
         );
+        $this->assertSame('warning', $contract['backend_capabilities']['cache']['dispatch_blocking_severity']);
+        $this->assertSame('acceleration_only', $contract['backend_capabilities']['cache']['role']);
         $this->assertSame('avro', $contract['backend_capabilities']['codec']['default_for_new_v2_runs']);
         $this->assertSame(
             'evaluated_by_backend_capabilities_snapshot',
             $contract['effective_states']['dispatch']['state']
         );
+        $this->assertStringContainsString(
+            'cache diagnostics stay warning-only',
+            $contract['effective_states']['dispatch']['blocking_rule']
+        );
     }
 
     public function testSnapshotCanInspectAnExplicitTaskQueueConnection(): void
@@ -372,6 +381,8 @@ public function testSnapshotIncludesSeverityRollupOfOkWhenAdmissionIsClean(): vo
                 ->set('cache.default', 'array');
             config()
                 ->set('cache.stores.array.driver', 'array');
+            config()
+                ->set('workflows.serializer', 'avro');
 
             $snapshot = BackendCapabilities::snapshot();
 
@@ -439,4 +450,49 @@ public function testSnapshotSeverityRollupReportsErrorWhenAnyIssueIsErrorSeverit
         $this->assertSame('error', $snapshot['severity']);
         $this->assertFalse($snapshot['supported']);
     }
+
+    public function testCustomNoLockCacheStoreIsWarningOnlyAndDoesNotFailSupport(): void
+    {
+        config()->set('database.default', 'pgsql');
+        config()
+            ->set('database.connections.pgsql.driver', 'pgsql');
+        config()
+            ->set('queue.default', 'redis');
+        config()
+            ->set('queue.connections.redis.driver', 'redis');
+        config()
+            ->set('workflows.serializer', 'avro');
+        $this->configureNonLockingCacheStore();
+
+        $snapshot = BackendCapabilities::snapshot();
+
+        $this->assertTrue($snapshot['supported']);
+        $this->assertTrue(BackendCapabilities::isSupported($snapshot));
+        $this->assertTrue($snapshot['cache']['supported']);
+        $this->assertSame('warning', $snapshot['severity']);
+
+        $cacheIssue = collect($snapshot['issues'])->firstWhere('code', 'cache_locks_unsupported');
+        $this->assertNotNull($cacheIssue);
+        $this->assertSame('warning', $cacheIssue['severity']);
+        $this->assertStringContainsString('Wake acceleration remains optional', $cacheIssue['message']);
+    }
+
+    private function configureNonLockingCacheStore(): void
+    {
+        $driver = 'test-non-locking';
+        $store = 'test-non-locking';
+
+        $this->app['cache']->extend($driver, function (): Repository {
+            if (! $this instanceof CacheManager) {
+                throw new \RuntimeException('Unexpected cache manager binding.');
+            }
+
+            return new Repository(new NonLockingCacheStore());
+        });
+
+        config()
+            ->set("cache.stores.{$store}.driver", $driver);
+        config()
+            ->set('cache.default', $store);
+    }
 }
diff --git a/tests/Unit/V2/HealthCheckTest.php b/tests/Unit/V2/HealthCheckTest.php
