Expose topology summaries on health endpoints

Author: durable-workflow-ops

README.md

@@ -495,8 +495,8 @@ workflow-task command payload.
 ## API Overview
 
 ### System
-- `GET /api/health` — Health check
-- `GET /api/ready` — Readiness check for migrations, default namespace, cache, auth config, and workflow v2 rollout-safety health
+- `GET /api/health` — Health check plus a machine-readable topology summary for the current node
+- `GET /api/ready` — Readiness check for migrations, default namespace, cache, auth config, workflow v2 rollout-safety health, and the current node topology summary
 - `GET /api/cluster/info` — Server capabilities, role topology, coordination-health summary, and version
 - `GET /api/system/health` — Full rollout-safety health snapshot for the requested namespace, including check status, categories, routing-drain state, operator metrics, and structural limits
 - `GET /api/system/metrics` — Server metrics including bounded stuck workflow-task diagnostics
@@ -703,7 +703,12 @@ class. Nodes that do not host the server's current HTTP control surface return
 `503` with `reason: "topology_role_unavailable"` on role-gated routes instead
 of pretending to be interchangeable HTTP peers. `GET /api/cluster/info`,
 `/api/health`, and `/api/ready` stay available for discovery and liveness even
-on scheduler-only, execution-only, or matching-only nodes.
+on scheduler-only, execution-only, or matching-only nodes. The unauthenticated
+health and readiness probes publish the current node's topology summary
+(`schema`, `version`, `current_shape`, `current_process_class`,
+`current_roles`, `execution_mode`, and `matching_role`) so operators can
+identify split-role nodes without authenticating into the broader
+`/api/cluster/info` manifest.
 
 Those runtime-serving write and poll routes also fail closed on bootstrap
 blockers. If database connectivity or workflow-table migrations are not ready,

app/Http/Controllers/Api/HealthController.php

@@ -47,6 +47,7 @@ public function check(): JsonResponse
             'checks' => [
                 'database' => $dbHealthy ? 'ok' : 'unavailable',
             ],
+            'topology' => ServerTopology::healthSummary(),
         ], $dbHealthy ? 200 : 503);
     }
 
@@ -59,6 +60,7 @@ public function ready(): JsonResponse
             'status' => $ready ? 'ready' : 'not_ready',
             'timestamp' => now()->toIso8601String(),
             'checks' => $snapshot['checks'],
+            'topology' => ServerTopology::healthSummary(),
         ], $ready ? 200 : 503);
     }
 

app/Support/ServerTopology.php

@@ -62,6 +62,24 @@ public static function info(): array
         ];
     }
 
+    /**
+     * @return array<string, mixed>
+     */
+    public static function healthSummary(): array
+    {
+        $currentNode = self::currentNode();
+
+        return [
+            'schema' => self::SCHEMA,
+            'version' => self::VERSION,
+            'current_shape' => $currentNode['shape'],
+            'current_process_class' => $currentNode['process_class'],
+            'current_roles' => $currentNode['roles'],
+            'execution_mode' => self::executionMode(),
+            'matching_role' => self::matchingRole(),
+        ];
+    }
+
     /**
      * @param  array<string, array{process_classes: list<array{name: string, roles: list<string>}>}>|null  $shapeAssignments
      * @return array{shape: string, process_class: string, roles: list<string>}

tests/Feature/HealthControllerTest.php

@@ -5,6 +5,7 @@
 namespace Tests\Feature;
 
 use App\Models\WorkflowNamespace;
+use App\Support\ServerTopology;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Schema;
@@ -23,7 +24,33 @@ public function test_health_check_returns_serving_when_database_is_available():
         $response->assertOk()
             ->assertJsonPath('status', 'serving')
             ->assertJsonPath('checks.database', 'ok')
-            ->assertJsonStructure(['status', 'timestamp', 'checks' => ['database']]);
+            ->assertJsonPath('topology.schema', ServerTopology::SCHEMA)
+            ->assertJsonPath('topology.version', ServerTopology::VERSION)
+            ->assertJsonPath('topology.current_shape', 'standalone_server')
+            ->assertJsonPath('topology.current_process_class', 'server_http_node')
+            ->assertJsonPath('topology.execution_mode', 'remote_worker_protocol')
+            ->assertJsonPath('topology.matching_role.shape', 'in_worker')
+            ->assertJsonStructure([
+                'status',
+                'timestamp',
+                'checks' => ['database'],
+                'topology' => [
+                    'schema',
+                    'version',
+                    'current_shape',
+                    'current_process_class',
+                    'current_roles',
+                    'execution_mode',
+                    'matching_role' => [
+                        'queue_wake_enabled',
+                        'shape',
+                        'wake_owner',
+                        'task_dispatch_mode',
+                        'partition_primitives',
+                        'backpressure_model',
+                    ],
+                ],
+            ]);
     }
 
     public function test_health_check_returns_degraded_when_database_is_unavailable(): void
@@ -95,7 +122,45 @@ public function test_readiness_check_returns_ready_when_bootstrap_state_is_avail
             ->assertJsonPath('checks.cache.status', 'ok')
             ->assertJsonPath('checks.auth.status', 'ok')
             ->assertJsonPath('checks.workflow_v2.status', 'ok')
-            ->assertJsonPath('checks.workflow_v2.http_status', 200);
+            ->assertJsonPath('checks.workflow_v2.http_status', 200)
+            ->assertJsonPath('topology.schema', ServerTopology::SCHEMA)
+            ->assertJsonPath('topology.version', ServerTopology::VERSION)
+            ->assertJsonPath('topology.current_shape', 'standalone_server')
+            ->assertJsonPath('topology.current_process_class', 'server_http_node')
+            ->assertJsonPath('topology.execution_mode', 'remote_worker_protocol')
+            ->assertJsonPath('topology.matching_role.task_dispatch_mode', 'poll');
+    }
+
+    public function test_public_health_endpoints_publish_topology_for_split_execution_nodes(): void
+    {
+        WorkflowNamespace::query()->create([
+            'name' => 'default',
+            'description' => 'Default namespace',
+            'retention_days' => 30,
+            'status' => 'active',
+        ]);
+
+        config([
+            'server.topology.shape' => 'split_control_execution',
+            'server.topology.process_class' => 'execution_node',
+        ]);
+
+        $this->getJson('/api/health')
+            ->assertOk()
+            ->assertJsonPath('topology.schema', ServerTopology::SCHEMA)
+            ->assertJsonPath('topology.current_shape', 'split_control_execution')
+            ->assertJsonPath('topology.current_process_class', 'execution_node')
+            ->assertJsonPath('topology.current_roles.0', 'execution_plane')
+            ->assertJsonPath('topology.execution_mode', 'remote_worker_protocol')
+            ->assertJsonPath('topology.matching_role.backpressure_model', 'lease_ownership');
+
+        $this->getJson('/api/ready')
+            ->assertOk()
+            ->assertJsonPath('topology.schema', ServerTopology::SCHEMA)
+            ->assertJsonPath('topology.current_shape', 'split_control_execution')
+            ->assertJsonPath('topology.current_process_class', 'execution_node')
+            ->assertJsonPath('topology.current_roles.0', 'execution_plane')
+            ->assertJsonPath('topology.matching_role.shape', 'in_worker');
     }
 
     public function test_readiness_check_warns_when_existing_create_table_migration_only_needs_adoption(): void