Classify v2 health checks as correctness or acceleration

Every entry returned by Workflow\V2\Support\HealthCheck::snapshot()
now carries an explicit category of correctness or acceleration, and
the snapshot exposes a categories rollup so operator surfaces can
answer two questions independently: is work being discovered from the
durable dispatch substrate, and is the acceleration layer propagating
through the configured cache or wake backend.

Add a dedicated long_poll_wake_acceleration check that reports the
configured cache backend's multi-node capability via
LongPollCacheValidator. Per the scheduler correctness contract, this
check never escalates above warning even when the wake backend is
unreachable: the acceleration layer is optional, and durable
discovery continues via bounded polling when wake signalling is
degraded. The existing eight checks retain their semantics and stay
in the correctness category.

Pin the new contract language in docs/architecture/scheduler-correctness.md
and docs/architecture/operational-liveness.md, and extend
SchedulerCorrectnessDocumentationTest plus OperationalLivenessDocumentationTest
so the category field, the acceleration check name, and the
no-escalation rule cannot silently drift. HealthCheckTest gains
three scenarios that cover every check being categorized, the
category rollup being consistent with the check list, and the
acceleration check reporting warning rather than error when the
cache backend is incompatible with the configured multi-node
topology.

Author: durable-workflow-ops

docs/architecture/operational-liveness.md

@@ -660,7 +660,7 @@ liveness (sub-keys under the named groups):
   surfaced as metrics so a dashboard can read them without reading
   config.
 
-The eight frozen health check names under `HealthCheck::snapshot()`:
+The nine frozen health check names under `HealthCheck::snapshot()`:
 
 - `backend_capabilities`
 - `run_summary_projection`
@@ -670,6 +670,14 @@ The eight frozen health check names under `HealthCheck::snapshot()`:
 - `task_transport`
 - `durable_resume_paths`
 - `worker_compatibility`
+- `long_poll_wake_acceleration`
+
+Every check entry also carries a `category` of `correctness` or
+`acceleration`. `long_poll_wake_acceleration` is the only entry
+whose `category` is `acceleration`; it reports wake-layer
+reachability and the acceleration contract (see
+`docs/architecture/scheduler-correctness.md`) forbids it from
+escalating above `warning`.
 
 Rules:
 

docs/architecture/scheduler-correctness.md

@@ -434,9 +434,14 @@ through the following surfaces.
   correctness healthy?"
 - `Workflow\V2\Support\HealthCheck::snapshot()` — reports
   `backend_capabilities`, `task_transport`, `durable_resume_paths`,
-  and `worker_compatibility` check status. Acceleration-layer
-  issues appear here as `warning`; correctness-substrate issues
-  appear as `error`.
+  `worker_compatibility`, and `long_poll_wake_acceleration` check
+  status. Each check carries an explicit `category` field whose
+  value is either `correctness` or `acceleration`. The snapshot
+  also exposes a `categories` map with a rolled-up `status` per
+  category so a single response answers the two operator
+  questions below without re-aggregating the check list.
+  Acceleration-layer issues appear as `warning`;
+  correctness-substrate issues appear as `error`.
 - `Workflow\V2\Support\OperatorQueueVisibility::forNamespace()`
   and `::forQueue()` — per-partition depth and claim state
   derived from `workflow_tasks`.
@@ -458,6 +463,14 @@ Guarantees:
 - Operators MUST be able to answer "is work being discovered?"
   and "is the acceleration layer propagating?" as separate
   questions, from separate metrics.
+- Every `HealthCheck::snapshot()` check entry MUST carry a
+  `category` of `correctness` or `acceleration`. The
+  `long_poll_wake_acceleration` check is the acceleration-layer
+  surface and MUST NOT raise its status above `warning` even
+  when the configured backend is unreachable, because the
+  acceleration layer is optional by contract. Correctness
+  checks remain free to report `error` when the durable
+  substrate is broken.
 
 ## Test strategy alignment
 

src/V2/Support/HealthCheck.php

@@ -5,9 +5,15 @@
 namespace Workflow\V2\Support;
 
 use Carbon\CarbonInterface;
+use Illuminate\Contracts\Cache\Repository as CacheRepository;
+use Illuminate\Support\Facades\App;
 
 final class HealthCheck
 {
+    public const CATEGORY_CORRECTNESS = 'correctness';
+
+    public const CATEGORY_ACCELERATION = 'acceleration';
+
     /**
      * @return array<string, mixed>
      */
@@ -24,6 +30,7 @@ public static function snapshot(?CarbonInterface $now = null): array
             self::taskTransportCheck($metrics['tasks'] ?? [], $metrics['backlog'] ?? []),
             self::durableResumePathCheck($metrics['backlog'] ?? [], $metrics['repair'] ?? []),
             self::workerCompatibilityCheck($metrics['workers'] ?? []),
+            self::longPollWakeAccelerationCheck(),
         ];
         $status = self::status($checks);
 
@@ -32,6 +39,7 @@ public static function snapshot(?CarbonInterface $now = null): array
             'status' => $status,
             'healthy' => $status !== 'error',
             'checks' => $checks,
+            'categories' => self::categorySummary($checks),
             'operator_metrics' => $metrics,
             'structural_limits' => StructuralLimits::snapshot(),
         ];
@@ -60,6 +68,7 @@ private static function backendCheck(array $backend): array
             $supported
                 ? 'The configured database, queue, and cache backends satisfy the v2 capability contract.'
                 : 'One or more configured v2 backend capabilities are unsupported.',
+            self::CATEGORY_CORRECTNESS,
             [
                 'issue_count' => count($issues),
                 'issues' => $issues,
@@ -81,6 +90,7 @@ private static function runSummaryProjectionCheck(array $projection): array
             $needsRebuild === 0
                 ? 'Run-summary projections are aligned with durable v2 runs.'
                 : 'Run-summary projections are missing, stale, schema-outdated, or orphaned; rebuild them before trusting Waterline lists.',
+            self::CATEGORY_CORRECTNESS,
             [
                 'needs_rebuild' => $needsRebuild,
                 'missing' => self::integer($projection['missing'] ?? 0),
@@ -120,6 +130,7 @@ private static function selectedRunProjectionCheck(array $projections): array
             $needsRebuild === 0
                 ? 'Selected-run wait, timeline, timer, and lineage projections are aligned with durable v2 detail.'
                 : 'Selected-run wait, timeline, timer, or lineage projections need rebuild before trusting Waterline detail.',
+            self::CATEGORY_CORRECTNESS,
             [
                 'needs_rebuild' => $needsRebuild,
                 'run_waits_needs_rebuild' => $waitNeedsRebuild,
@@ -160,6 +171,7 @@ private static function historyRetentionInvariantCheck(array $history): array
             $orphaned === 0
                 ? 'Workflow history events all reference retained workflow runs.'
                 : 'Workflow history events exist without retained workflow runs; retention cleanup must reconcile them.',
+            self::CATEGORY_CORRECTNESS,
             [
                 'history_orphan_total' => $orphaned,
                 'events' => self::integer($history['events'] ?? 0),
@@ -181,6 +193,7 @@ private static function commandContractCheck(array $metrics): array
             $needed === 0
                 ? 'WorkflowStarted command-contract snapshots are complete.'
                 : 'Some WorkflowStarted command-contract snapshots need backfill before operators can trust command forms.',
+            self::CATEGORY_CORRECTNESS,
             [
                 'backfill_needed_runs' => $needed,
                 'backfill_available_runs' => self::integer($metrics['backfill_available_runs'] ?? 0),
@@ -204,6 +217,7 @@ private static function taskTransportCheck(array $tasks, array $backlog): array
             $unhealthyTasks === 0
                 ? 'No unhealthy durable task transport state is currently projected.'
                 : 'One or more durable tasks have unhealthy transport, claim, dispatch, or lease state.',
+            self::CATEGORY_CORRECTNESS,
             [
                 'unhealthy_tasks' => $unhealthyTasks,
                 'repair_needed_runs' => self::integer($backlog['repair_needed_runs'] ?? 0),
@@ -228,6 +242,7 @@ private static function durableResumePathCheck(array $backlog, array $repair): a
             $repairNeededRuns === 0
                 ? 'Every open v2 run has a projected durable resume path.'
                 : 'One or more open v2 runs are missing their durable next-resume source and need repair.',
+            self::CATEGORY_CORRECTNESS,
             [
                 'repair_needed_runs' => $repairNeededRuns,
                 'missing_task_candidates' => self::integer($repair['missing_task_candidates'] ?? 0),
@@ -258,6 +273,7 @@ private static function workerCompatibilityCheck(array $workers): array
                 $required === null
                     ? 'No current v2 compatibility marker is required.'
                     : 'At least one active worker heartbeat advertises the current v2 compatibility marker.',
+                self::CATEGORY_CORRECTNESS,
                 [
                     'required_compatibility' => $required,
                     'active_workers' => self::integer($workers['active_workers'] ?? 0),
@@ -271,6 +287,7 @@ private static function workerCompatibilityCheck(array $workers): array
             'worker_compatibility',
             'warning',
             'No active worker heartbeat advertises the current v2 compatibility marker.',
+            self::CATEGORY_CORRECTNESS,
             [
                 'required_compatibility' => $required,
                 'active_workers' => self::integer($workers['active_workers'] ?? 0),
@@ -280,6 +297,112 @@ private static function workerCompatibilityCheck(array $workers): array
         );
     }
 
+    /**
+     * Acceleration-layer health for the long-poll wake surface.
+     *
+     * The wake layer is optional by contract: correctness continues even
+     * when this check reports `warning`. The check exists so operators
+     * can answer "is the acceleration layer propagating?" as a separate
+     * question from "is work being discovered?".
+     *
+     * @return array<string, mixed>
+     */
+    private static function longPollWakeAccelerationCheck(): array
+    {
+        $multiNode = (bool) config('workflows.v2.long_poll.multi_node', false);
+        $data = [
+            'multi_node' => $multiNode,
+            'backend' => null,
+            'capable' => null,
+            'safe' => null,
+            'reason' => null,
+        ];
+
+        $cache = self::resolveCacheRepository();
+
+        if ($cache === null) {
+            return self::check(
+                'long_poll_wake_acceleration',
+                'warning',
+                'Cache repository is not resolvable; wake acceleration may be disabled. Durable discovery continues via bounded polling.',
+                self::CATEGORY_ACCELERATION,
+                $data,
+            );
+        }
+
+        $validator = new LongPollCacheValidator();
+        $capability = $validator->validateMultiNodeCapable($cache);
+        $safety = $validator->checkMultiNodeSafety($cache, $multiNode);
+
+        $data['backend'] = is_string($capability['backend'] ?? null) ? $capability['backend'] : null;
+        $data['capable'] = (bool) ($capability['capable'] ?? false);
+        $data['safe'] = (bool) ($safety['safe'] ?? true);
+        $data['reason'] = is_string($safety['message'] ?? null)
+            ? $safety['message']
+            : (is_string($capability['reason'] ?? null) ? $capability['reason'] : null);
+
+        if ($data['safe'] === true) {
+            return self::check(
+                'long_poll_wake_acceleration',
+                'ok',
+                $multiNode
+                    ? 'Wake acceleration backend is multi-node capable; dispatch discovery benefits from sub-second signalling.'
+                    : 'Wake acceleration backend is configured; dispatch discovery benefits from sub-second signalling.',
+                self::CATEGORY_ACCELERATION,
+                $data,
+            );
+        }
+
+        return self::check(
+            'long_poll_wake_acceleration',
+            'warning',
+            $data['reason'] ?? 'Wake acceleration layer is degraded; durable discovery continues via bounded polling.',
+            self::CATEGORY_ACCELERATION,
+            $data,
+        );
+    }
+
+    private static function resolveCacheRepository(): ?CacheRepository
+    {
+        try {
+            return App::make(CacheRepository::class);
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+
+    /**
+     * Summarize check status per category so operators can answer
+     * "is work being discovered?" (correctness) and "is the
+     * acceleration layer propagating?" (acceleration) as separate
+     * questions without re-aggregating the check list.
+     *
+     * @param list<array<string, mixed>> $checks
+     * @return array<string, array<string, mixed>>
+     */
+    private static function categorySummary(array $checks): array
+    {
+        $categories = [
+            self::CATEGORY_CORRECTNESS => [],
+            self::CATEGORY_ACCELERATION => [],
+        ];
+
+        foreach ($checks as $check) {
+            $category = $check['category'] ?? self::CATEGORY_CORRECTNESS;
+            $categories[$category][] = $check;
+        }
+
+        $summaries = [];
+        foreach ($categories as $name => $entries) {
+            $summaries[$name] = [
+                'status' => self::status($entries),
+                'check_count' => count($entries),
+            ];
+        }
+
+        return $summaries;
+    }
+
     /**
      * @param list<array<string, mixed>> $checks
      */
@@ -302,11 +425,12 @@ private static function status(array $checks): string
      * @param array<string, mixed> $data
      * @return array<string, mixed>
      */
-    private static function check(string $name, string $status, string $message, array $data): array
+    private static function check(string $name, string $status, string $message, string $category, array $data): array
     {
         return [
             'name' => $name,
             'status' => $status,
+            'category' => $category,
             'message' => $message,
             'data' => $data,
         ];

tests/Unit/V2/HealthCheckTest.php

@@ -617,4 +617,86 @@ public function testSnapshotWarnsWhenRunSummaryProjectionSchemaIsOutdated(): voi
         $this->assertSame(1, $projection['data']['schema_outdated']);
         $this->assertSame(RunSummaryProjector::SCHEMA_VERSION, $projection['data']['projection_schema_version']);
     }
+
+    public function testSnapshotClassifiesEveryCheckAsCorrectnessOrAcceleration(): void
+    {
+        config()->set('queue.default', 'redis');
+        config()->set('queue.connections.redis.driver', 'redis');
+        config()->set('cache.default', 'array');
+        config()->set('cache.stores.array.driver', 'array');
+
+        $snapshot = HealthCheck::snapshot();
+
+        $this->assertNotEmpty($snapshot['checks']);
+        $allowed = [HealthCheck::CATEGORY_CORRECTNESS, HealthCheck::CATEGORY_ACCELERATION];
+
+        foreach ($snapshot['checks'] as $check) {
+            $this->assertArrayHasKey('category', $check, sprintf(
+                'HealthCheck entry %s must expose a category field so operators can separate correctness from acceleration.',
+                $check['name'] ?? 'unknown',
+            ));
+            $this->assertContains($check['category'], $allowed, sprintf(
+                'HealthCheck entry %s has invalid category %s; must be correctness or acceleration.',
+                $check['name'] ?? 'unknown',
+                (string) ($check['category'] ?? ''),
+            ));
+        }
+
+        $this->assertArrayHasKey('categories', $snapshot);
+        $this->assertArrayHasKey('correctness', $snapshot['categories']);
+        $this->assertArrayHasKey('acceleration', $snapshot['categories']);
+
+        $correctnessChecks = collect($snapshot['checks'])
+            ->where('category', HealthCheck::CATEGORY_CORRECTNESS)
+            ->count();
+        $accelerationChecks = collect($snapshot['checks'])
+            ->where('category', HealthCheck::CATEGORY_ACCELERATION)
+            ->count();
+
+        $this->assertSame($correctnessChecks, $snapshot['categories']['correctness']['check_count']);
+        $this->assertSame($accelerationChecks, $snapshot['categories']['acceleration']['check_count']);
+        $this->assertGreaterThan(0, $correctnessChecks);
+        $this->assertGreaterThan(0, $accelerationChecks);
+
+        $wake = collect($snapshot['checks'])->firstWhere('name', 'long_poll_wake_acceleration');
+        $this->assertNotNull($wake, 'HealthCheck must expose a long_poll_wake_acceleration check.');
+        $this->assertSame(HealthCheck::CATEGORY_ACCELERATION, $wake['category']);
+    }
+
+    public function testLongPollWakeAccelerationCheckNeverEscalatesAboveWarning(): void
+    {
+        config()->set('queue.default', 'redis');
+        config()->set('queue.connections.redis.driver', 'redis');
+        config()->set('cache.default', 'file');
+        config()->set('cache.stores.file.driver', 'file');
+        config()->set('workflows.v2.long_poll.multi_node', true);
+
+        $snapshot = HealthCheck::snapshot();
+        $wake = collect($snapshot['checks'])->firstWhere('name', 'long_poll_wake_acceleration');
+
+        $this->assertNotNull($wake);
+        $this->assertContains(
+            $wake['status'],
+            ['ok', 'warning'],
+            'Acceleration-layer check must never escalate to error; correctness remains independent of the acceleration layer.',
+        );
+        $this->assertSame('warning', $wake['status']);
+        $this->assertFalse($wake['data']['safe']);
+        $this->assertNotNull($wake['data']['reason']);
+    }
+
+    public function testLongPollWakeAccelerationReportsOkWhenBackendIsCapable(): void
+    {
+        config()->set('cache.default', 'array');
+        config()->set('cache.stores.array.driver', 'array');
+        config()->set('workflows.v2.long_poll.multi_node', false);
+
+        $snapshot = HealthCheck::snapshot();
+        $wake = collect($snapshot['checks'])->firstWhere('name', 'long_poll_wake_acceleration');
+
+        $this->assertNotNull($wake);
+        $this->assertSame('ok', $wake['status']);
+        $this->assertSame(HealthCheck::CATEGORY_ACCELERATION, $wake['category']);
+        $this->assertArrayHasKey('backend', $wake['data']);
+    }
 }

tests/Unit/V2/OperationalLivenessDocumentationTest.php

@@ -191,6 +191,7 @@ final class OperationalLivenessDocumentationTest extends TestCase
         'task_transport',
         'durable_resume_paths',
         'worker_compatibility',
+        'long_poll_wake_acceleration',
     ];
 
     private const REQUIRED_MIGRATIONS = [