GitHub #250: Waterline Phase 4: Polish and Accessibility (#511)

Author: durable-workflow-ops

docs/architecture/worker-compatibility.md

@@ -84,8 +84,13 @@ It does not cover:
 
 Every live worker maintains a heartbeat row under the
 `workflow_worker_compatibility_heartbeats` table (or the legacy fallback
-cache when the table is unavailable). The row is owned by one
-`worker_id` and carries:
+cache when the table is unavailable). The fleet auto-detects a missing
+table and routes to the cache; operators can also force the cache-only
+path by setting
+`workflows.v2.compatibility.disable_heartbeat_table`
+(`DW_V2_COMPATIBILITY_DISABLE_HEARTBEAT_TABLE`) to true without dropping
+the table — useful for sidelining the table during a problematic schema
+transition. The row is owned by one `worker_id` and carries:
 
 - **`worker_id`** — `hostname:pid:ulid`, generated on first heartbeat
   and stable for the life of the worker process. The ULID segment keeps

src/V2/Support/WorkerCompatibilityFleet.php

@@ -915,6 +915,10 @@ private static function normalizeQueues(?string $queue): array
 
     private static function heartbeatTableExists(): bool
     {
+        if ((bool) config('workflows.v2.compatibility.disable_heartbeat_table', false)) {
+            return false;
+        }
+
         try {
             return Schema::hasTable((new WorkerCompatibilityHeartbeat())->getTable());
         } catch (Throwable) {

src/config/workflows.php

@@ -108,6 +108,21 @@
                 'WORKFLOW_V2_PIN_TO_RECORDED_FINGERPRINT',
                 true
             ),
+            // When true, the worker-compatibility fleet bypasses the
+            // workflow_worker_compatibility_heartbeats table and reads/writes
+            // exclusively through the legacy cache fallback. The fleet
+            // already auto-detects a missing table and falls back to cache,
+            // so the default (false) is correct for almost every deployment.
+            // Set this to true when you need to force the cache-only path
+            // without dropping the table — operators who want to temporarily
+            // sideline the heartbeat table during a problematic schema
+            // transition, and tests that exercise the cache-fallback branch
+            // without mutating shared schema state.
+            'disable_heartbeat_table' => (bool) Env::dw(
+                'DW_V2_COMPATIBILITY_DISABLE_HEARTBEAT_TABLE',
+                'WORKFLOW_V2_COMPATIBILITY_DISABLE_HEARTBEAT_TABLE',
+                false
+            ),
         ],
         'history_budget' => [
             'continue_as_new_event_threshold' => (int) Env::dw(

tests/Feature/V2/V2OperatorMetricsTest.php

@@ -5,7 +5,6 @@
 namespace Tests\Feature\V2;
 
 use Illuminate\Support\Carbon;
-use Illuminate\Support\Facades\Schema;
 use Tests\TestCase;
 use Workflow\V2\Enums\ActivityStatus;
 use Workflow\V2\Enums\CommandOutcome;
@@ -50,31 +49,26 @@ public function testWorkerFleetSnapshotFallsBackToCacheWhenHeartbeatTableIsUnava
             ->set('workflows.v2.compatibility.namespace', 'metrics-test');
 
         WorkerCompatibilityFleet::clear();
-        Schema::dropIfExists('workflow_worker_compatibility_heartbeats');
-
-        try {
-            WorkerCompatibilityFleet::record(['build-a'], 'redis', 'default', 'worker-a');
-
-            $snapshot = OperatorMetrics::snapshot();
-
-            $this->assertSame(1, $snapshot['workers']['active_workers']);
-            $this->assertSame(1, $snapshot['workers']['active_worker_scopes']);
-            $this->assertSame(1, $snapshot['workers']['active_workers_supporting_required']);
-            $this->assertCount(1, $snapshot['workers']['fleet']);
-            $this->assertSame('worker-a', $snapshot['workers']['fleet'][0]['worker_id']);
-            $this->assertSame('cache', $snapshot['workers']['fleet'][0]['source']);
-            $this->assertTrue($snapshot['workers']['fleet'][0]['supports_required']);
-        } finally {
-            // Restore the dropped table within this test so the next test
-            // does not depend on Testbench's per-test migrate:fresh racing
-            // to re-create it. Re-running the migration's up() keeps the
-            // restored schema in sync with the canonical definition.
-            if (! Schema::hasTable('workflow_worker_compatibility_heartbeats')) {
-                $migration = require __DIR__
-                    . '/../../../src/migrations/2026_04_08_000126_create_worker_compatibility_heartbeats_table.php';
-                $migration->up();
-            }
-        }
+
+        // Force the fleet onto the legacy cache-only path via configuration
+        // instead of dropping the heartbeats table. Dropping the table
+        // mutated shared schema state and depended on Testbench's per-test
+        // migrate:fresh in the next test to restore it, which raced when
+        // the file's tests ran back-to-back in a single PHPUnit process.
+        config()
+            ->set('workflows.v2.compatibility.disable_heartbeat_table', true);
+
+        WorkerCompatibilityFleet::record(['build-a'], 'redis', 'default', 'worker-a');
+
+        $snapshot = OperatorMetrics::snapshot();
+
+        $this->assertSame(1, $snapshot['workers']['active_workers']);
+        $this->assertSame(1, $snapshot['workers']['active_worker_scopes']);
+        $this->assertSame(1, $snapshot['workers']['active_workers_supporting_required']);
+        $this->assertCount(1, $snapshot['workers']['fleet']);
+        $this->assertSame('worker-a', $snapshot['workers']['fleet'][0]['worker_id']);
+        $this->assertSame('cache', $snapshot['workers']['fleet'][0]['source']);
+        $this->assertTrue($snapshot['workers']['fleet'][0]['supports_required']);
     }
 
     public function testWorkerFleetSnapshotUsesRequestedNamespaceInsteadOfConfiguredCompatibilityNamespace(): void