Require the published workflow health contract in Waterline

durable-workflow-ops · durable-workflow-ops · commit e7a0f78a5da6 · 2026-04-29T18:40:59.000Z
Require durable-workflow/workflow ^2.0.0-alpha.27 so Waterline can rely on the namespace-scoped v2 health snapshot and the current schedule mutation signatures.

Remove compatibility shims for older workflow alphas and extend the API-floor test coverage to assert the HealthCheck snapshot namespace parameter.
diff --git a/app/Http/Controllers/V2HealthController.php b/app/Http/Controllers/V2HealthController.php
@@ -9,9 +9,7 @@
 use Workflow\V2\Enums\TaskStatus;
 use Workflow\V2\Enums\TaskType;
 use Workflow\V2\Support\HealthCheck;
-use Workflow\V2\Support\OperatorMetrics;
 use Workflow\V2\Support\StandaloneWorkerVisibility;
-use Workflow\V2\Support\StructuralLimits;
 use Workflow\V2\Support\TaskRepairPolicy;
 use Workflow\V2\Models\WorkflowTask;
 
@@ -577,74 +575,15 @@ private function queueVisibilityAlerts(array $queueVisibility): array
     }
 
     /**
-     * Keep Waterline compatible with both the released alpha package and the
-     * newer workflow branch while health snapshots gain namespace scoping.
+     * Waterline relies on the namespace-scoped v2 health snapshot contract.
+     * WorkflowPackageApiFloor asserts the required signature at boot whenever
+     * the resolved engine source is v2.
      *
      * @return array<string, mixed>
      */
     private function snapshotForConfiguredNamespace(): array
     {
-        $namespace = $this->namespace();
-        $now = now();
-
-        if ((new \ReflectionMethod(HealthCheck::class, 'snapshot'))->getNumberOfParameters() >= 2) {
-            return HealthCheck::snapshot($now, $namespace);
-        }
-
-        $metrics = OperatorMetrics::snapshot($now, $namespace);
-        $checks = [
-            self::invokeLegacyHealthCheck('backendCheck', $metrics['backend'] ?? []),
-            self::invokeLegacyHealthCheck('runSummaryProjectionCheck', $metrics['projections']['run_summaries'] ?? []),
-            self::invokeLegacyHealthCheck('selectedRunProjectionCheck', $metrics['projections'] ?? []),
-            self::invokeLegacyHealthCheck('historyRetentionInvariantCheck', $metrics['history'] ?? []),
-            self::invokeLegacyHealthCheck('commandContractCheck', $metrics['command_contracts'] ?? []),
-            self::invokeLegacyHealthCheck('taskTransportCheck', $metrics['tasks'] ?? [], $metrics['backlog'] ?? []),
-        ];
-
-        if (self::legacyHealthCheckExists('routingHealthCheck')) {
-            $checks[] = self::invokeLegacyHealthCheck(
-                'routingHealthCheck',
-                $metrics['tasks'] ?? [],
-                $metrics['backlog'] ?? [],
-                $metrics['matching_role'] ?? [],
-                $metrics['workers'] ?? [],
-            );
-        }
-
-        $checks[] = self::invokeLegacyHealthCheck(
-            'durableResumePathCheck',
-            $metrics['backlog'] ?? [],
-            $metrics['repair'] ?? [],
-            $metrics['runs'] ?? [],
-        );
-        $checks[] = self::invokeLegacyHealthCheck('workerCompatibilityCheck', $metrics['workers'] ?? []);
-        $checks[] = self::invokeLegacyHealthCheck('schedulerRoleCheck', $metrics['schedules'] ?? []);
-        $checks[] = self::invokeLegacyHealthCheck('longPollWakeAccelerationCheck');
-        $status = self::invokeLegacyHealthCheck('status', $checks);
-
-        return [
-            'generated_at' => $metrics['generated_at'] ?? $now->toJSON(),
-            'status' => $status,
-            'healthy' => $status !== 'error',
-            'checks' => $checks,
-            'categories' => self::invokeLegacyHealthCheck('categorySummary', $checks),
-            'operator_metrics' => $metrics,
-            'structural_limits' => StructuralLimits::snapshot(),
-        ];
-    }
-
-    private static function invokeLegacyHealthCheck(string $method, mixed ...$args): mixed
-    {
-        return \Closure::bind(
-            static fn (string $method, array $args): mixed => HealthCheck::$method(...$args),
-            null,
-            HealthCheck::class,
-        )($method, $args);
-    }
-
-    private static function legacyHealthCheckExists(string $method): bool
-    {
-        return method_exists(HealthCheck::class, $method);
+        return HealthCheck::snapshot(now(), $this->namespace());
     }
 
     /**
diff --git a/app/Repositories/Workflow/Infrastructure/V2WorkflowRepository.php b/app/Repositories/Workflow/Infrastructure/V2WorkflowRepository.php
@@ -172,7 +172,6 @@ private function annotateOperatorMetrics(mixed $metrics, ?string $namespace): mi
         }
 
         $metrics['workers'] = $this->scopedWorkerMetrics($metrics['workers'] ?? null, $namespace);
-        $metrics['matching_role'] = $this->matchingRoleMetrics($metrics['matching_role'] ?? null);
 
         return $metrics;
     }
@@ -229,38 +228,6 @@ private function scopedWorkerMetrics(mixed $workers, ?string $namespace): mixed
         return $workers;
     }
 
-    /**
-     * The task-matching contract freezes the wake owner, partition
-     * primitives, and lease-based backpressure model even though older
-     * workflow alphas did not yet expose the full matching-role block on
-     * OperatorMetrics::snapshot().
-     *
-     * @param mixed $matchingRole
-     * @return mixed
-     */
-    private function matchingRoleMetrics(mixed $matchingRole): mixed
-    {
-        if (! is_array($matchingRole)) {
-            return $matchingRole;
-        }
-
-        if (! array_key_exists('wake_owner', $matchingRole)) {
-            $matchingRole['wake_owner'] = ($matchingRole['queue_wake_enabled'] ?? false) === true
-                ? 'worker_loop'
-                : 'dedicated_repair_pass';
-        }
-
-        if (! array_key_exists('partition_primitives', $matchingRole)) {
-            $matchingRole['partition_primitives'] = ['connection', 'queue', 'compatibility', 'namespace'];
-        }
-
-        if (! array_key_exists('backpressure_model', $matchingRole)) {
-            $matchingRole['backpressure_model'] = 'lease_ownership';
-        }
-
-        return $matchingRole;
-    }
-
     /**
      * @param array<string, mixed> $snapshot
      * @return array<string, mixed>
diff --git a/app/Support/WorkflowPackageApiFloor.php b/app/Support/WorkflowPackageApiFloor.php
@@ -11,21 +11,19 @@
  * Enforces the minimum `durable-workflow/workflow` API surface Waterline
  * relies on when the v2 operator bridge is active.
  *
- * Waterline's composer constraint (`^1.0 || ^2.0`) intentionally covers a
- * wide range because Waterline ships with a v1 fallback. The API floor
- * here only matters when the resolved engine source is v2 — a v1 install
- * or an `auto`-mode install that falls back to v1 never calls the v2
- * schedule mutation signatures and must boot cleanly even when the v2
- * classes are absent.
+ * Waterline now requires the published v2 alpha line of
+ * `durable-workflow/workflow`, but the API floor still only matters when the
+ * resolved engine source is v2. A v1 install or an `auto`-mode install that
+ * falls back to v1 never calls the v2 schedule mutation signatures and must
+ * boot cleanly even when the v2 classes are absent.
  *
- * Inside the v2 band, however, specific methods that carry
- * `CommandContext` for audit attribution landed only in workflow commit
- * `e59e6f2`. An older v2 install that predates that commit lacks the
- * context-accepting signatures and fails the Waterline schedule
- * pause/resume/trigger/backfill/delete routes with unknown-named-parameter
- * or argument-count errors. `assertIfActive()` is called at boot so those
- * broken pairings surface with a clear diagnostic instead of a 500 the
- * first time an operator clicks "Pause" in the UI.
+ * Inside the v2 band, however, Waterline now depends on specific schedule
+ * mutation signatures and the namespace-scoped v2 health snapshot. Older
+ * v2 installs that predate those contracts fail schedule mutation routes
+ * with unknown-named-parameter or argument-count errors, or silently lose
+ * namespace scoping on the operator health surface. `assertIfActive()` is
+ * called at boot so those broken pairings surface with a clear diagnostic
+ * instead of a 500 or a cross-namespace health payload at runtime.
  */
 final class WorkflowPackageApiFloor
 {
@@ -43,6 +41,7 @@ final class WorkflowPackageApiFloor
         [\Workflow\V2\Support\ScheduleManager::class, 'triggerDetailed', 'context'],
         [\Workflow\V2\Support\ScheduleManager::class, 'backfill', 'context'],
         [\Workflow\V2\Support\ScheduleManager::class, 'delete', 'context'],
+        [\Workflow\V2\Support\HealthCheck::class, 'snapshot', 'namespace'],
     ];
 
     public const COMMAND_CONTEXT_CLASS = \Workflow\V2\CommandContext::class;
@@ -92,7 +91,7 @@ public static function assertAgainst(
         throw new RuntimeException(sprintf(
             "Installed durable-workflow/workflow package is older than the API floor Waterline requires. "
             ."Missing: %s. Upgrade the workflow package to a v2 snapshot that includes CommandContext "
-            .'and the context-accepting schedule mutation signatures (see repos/workflow commit e59e6f2).',
+            .'plus the context-accepting schedule mutation and namespace-scoped health snapshot signatures.',
             implode(', ', $missing),
         ));
     }
diff --git a/composer.json b/composer.json
@@ -14,7 +14,7 @@
     "require": {
         "php": "^8.0.2",
         "illuminate/support": "^9.0|^10.0|^11.0|^12.0|^13.0",
-        "durable-workflow/workflow": "^2.0@dev"
+        "durable-workflow/workflow": "^2.0.0-alpha.27"
     },
     "require-dev": {
         "fakerphp/faker": "^1.9.1",
@@ -23,9 +23,6 @@
         "orchestra/workbench": "^7.29",
         "phpunit/phpunit": "^9.5.10|^12.5.12"
     },
-    "conflict": {
-        "durable-workflow/workflow": "<2.0.0-alpha.27"
-    },
     "autoload": {
         "psr-4": {
             "Waterline\\": "app/"
diff --git a/tests/Unit/Support/WorkflowPackageApiFloorTest.php b/tests/Unit/Support/WorkflowPackageApiFloorTest.php
@@ -7,6 +7,7 @@
 use Waterline\Support\WorkflowPackageApiFloor;
 use Waterline\Tests\TestCase;
 use Workflow\V2\CommandContext;
+use Workflow\V2\Support\HealthCheck;
 use Workflow\V2\Support\ScheduleManager;
 
 /**
@@ -58,6 +59,22 @@ public function test_find_missing_returns_empty_list_on_current_workflow_package
         $this->assertSame([], WorkflowPackageApiFloor::findMissing());
     }
 
+    public function test_health_check_snapshot_accepts_namespace_parameter(): void
+    {
+        $reflection = new ReflectionClass(HealthCheck::class);
+        $reflectionMethod = $reflection->getMethod('snapshot');
+
+        $this->assertTrue($reflectionMethod->isPublic(), 'snapshot is not public');
+        $this->assertTrue($reflectionMethod->isStatic(), 'snapshot is not static');
+
+        $parameterNames = array_map(
+            static fn ($parameter): string => $parameter->getName(),
+            $reflectionMethod->getParameters(),
+        );
+
+        $this->assertContains('namespace', $parameterNames, 'snapshot does not declare a $namespace parameter');
+    }
+
     public function test_find_missing_reports_missing_command_context_class(): void
     {
         $missing = WorkflowPackageApiFloor::findMissing(
@@ -142,7 +159,7 @@ public function test_assert_against_throws_with_aggregated_diagnostic_when_floor
         $this->expectExceptionMessage('older than the API floor Waterline requires');
         $this->expectExceptionMessage('NonExistentCommandContext');
         $this->expectExceptionMessage('thisMethodDoesNotExist');
-        $this->expectExceptionMessage('context-accepting schedule mutation signatures');
+        $this->expectExceptionMessage('namespace-scoped health snapshot signatures');
 
         WorkflowPackageApiFloor::assertAgainst(
             contextClass: 'Waterline\\Tests\\Unit\\Support\\NonExistentCommandContext',
