Pin operator_metrics.schedules.* scheduler-role keys on the dashboard payload

Add a feature test in V2DashboardStatsControllerTest that asserts the
frozen operator_metrics.schedules.* keys exposed by the workflow v2
package — active, paused, missed, oldest_overdue_at, max_overdue_ms,
fires_total, failures_total — so contract drift between the workflow
snapshot and the Waterline scheduler-role section of the dashboard
fails loudly in CI once a workflow alpha that emits the keys is
published.

The test self-skips when the resolved workflow alpha predates the
scheduler-role metrics surface (today's alpha.8 does not expose the
keys). The assertions pin automatically at the moment an alpha that
exposes operator_metrics.schedules lands, following the same pattern
used for the HealthCheck category contract.

Author: durable-workflow-ops

tests/Feature/V2DashboardStatsControllerTest.php

@@ -660,4 +660,53 @@ public function testIndexIncludesCommandContractBackfillMetrics(): void
             ->assertJsonPath('operator_metrics.command_contracts.backfill_available_runs', 1)
             ->assertJsonPath('operator_metrics.command_contracts.backfill_unavailable_runs', 1);
     }
+
+    public function testIndexExposesSchedulerRoleMetricsWhenWorkflowAlphaSupportsThem(): void
+    {
+        config()->set('waterline.engine_source', 'v2');
+
+        $response = $this->get('/waterline/api/stats')->assertStatus(200);
+
+        $schedules = $response->json('operator_metrics.schedules');
+
+        if ($schedules === null) {
+            // Older workflow alpha releases predate the scheduler-role
+            // metrics contract frozen in docs/architecture/rollout-safety.md.
+            // The dashboard gracefully hides the scheduler-role section when
+            // those keys are absent. Skip until an alpha that emits the
+            // schedules snapshot is published; the assertions below will
+            // pin automatically at that point.
+            $this->markTestSkipped(
+                'Resolved workflow package does not yet expose operator_metrics.schedules; '
+                    . 'test is a no-op until a workflow alpha that emits the scheduler-role '
+                    . 'metrics contract is published.'
+            );
+        }
+
+        $this->assertIsArray($schedules);
+        foreach (
+            ['active', 'paused', 'missed', 'oldest_overdue_at', 'max_overdue_ms', 'fires_total', 'failures_total']
+            as $key
+        ) {
+            $this->assertArrayHasKey(
+                $key,
+                $schedules,
+                sprintf('operator_metrics.schedules.%s must be present in the dashboard payload', $key),
+            );
+        }
+
+        $this->assertIsInt($schedules['active']);
+        $this->assertIsInt($schedules['paused']);
+        $this->assertIsInt($schedules['missed']);
+        $this->assertIsInt($schedules['fires_total']);
+        $this->assertIsInt($schedules['failures_total']);
+        $this->assertTrue(
+            $schedules['oldest_overdue_at'] === null || is_string($schedules['oldest_overdue_at']),
+            'operator_metrics.schedules.oldest_overdue_at must be null or ISO-8601 string',
+        );
+        $this->assertTrue(
+            $schedules['max_overdue_ms'] === null || is_int($schedules['max_overdue_ms']),
+            'operator_metrics.schedules.max_overdue_ms must be null or integer milliseconds',
+        );
+    }
 }