Publish server role topology through cluster discovery

Author: durable-workflow-ops

README.md

@@ -493,7 +493,7 @@ workflow-task command payload.
 ### System
 - `GET /api/health` — Health check
 - `GET /api/ready` — Readiness check for migrations, default namespace, cache, and auth config
-- `GET /api/cluster/info` — Server capabilities and version
+- `GET /api/cluster/info` — Server capabilities, role topology, and version
 - `GET /api/system/metrics` — Server metrics including bounded stuck workflow-task diagnostics
 - `GET /api/system/operator-metrics` — Full operator metrics snapshot (runs, tasks, backlog, repair, workers/fleet, backend, structural limits) for rollout-safety coordination health
 - `GET /api/system/repair` — Task repair diagnostics
@@ -652,6 +652,16 @@ Server-owned cache keys and metric label sets are governed by the bounded-growth
 policy in `config/dw-bounded-growth.php`; the human-readable inventory lives in
 `docs/bounded-growth.md`.
 
+Cluster discovery also publishes a `topology` manifest. It freezes the server's
+role vocabulary (`api_ingress`, `control_plane`, `matching`,
+`history_projection`, `scheduler`, `execution_plane`), the product's supported
+deployment shapes (`embedded`, `standalone_server`,
+`split_control_execution`), the roles currently hosted by the HTTP node, and
+the current execution mode. `execution_mode` is `remote_worker_protocol` in the
+default service-mode deployment and switches to `local_queue_worker` when
+`DW_MODE=embedded` routes workflow and activity task execution through local
+Laravel queue workers.
+
 The activity-grade external execution surface is published from
 `GET /api/cluster/info` at
 `worker_protocol.external_execution_surface_contract`. That manifest is the

app/Http/Controllers/Api/HealthController.php

@@ -7,6 +7,7 @@
 use App\Support\BridgeAdapterOutcomeContract;
 use App\Support\ClientCompatibility;
 use App\Support\ControlPlaneProtocol;
+use App\Support\ServerTopology;
 use App\Support\ServerReadiness;
 use App\Support\WorkerProtocol;
 use Illuminate\Http\JsonResponse;
@@ -117,6 +118,7 @@ public function clusterInfo(Request $request): JsonResponse
                 'max_pending_children' => (int) config('server.limits.max_pending_children', 2000),
             ],
             'structural_limits' => StructuralLimits::snapshot(),
+            'topology' => ServerTopology::info(),
             'client_compatibility' => ClientCompatibility::info(),
             'auth_composition_contract' => AuthCompositionContract::manifest(),
             'control_plane' => ControlPlaneProtocol::info(),

app/Support/ServerTopology.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace App\Support;
+
+final class ServerTopology
+{
+    public const SCHEMA = 'durable-workflow.v2.role-topology';
+
+    public const VERSION = 1;
+
+    private const SUPPORTED_SHAPES = [
+        'embedded',
+        'standalone_server',
+        'split_control_execution',
+    ];
+
+    private const ROLE_VOCABULARY = [
+        'api_ingress',
+        'control_plane',
+        'matching',
+        'history_projection',
+        'scheduler',
+        'execution_plane',
+    ];
+
+    private const CURRENT_SERVER_NODE_ROLES = [
+        'api_ingress',
+        'control_plane',
+        'matching',
+        'history_projection',
+    ];
+
+    /**
+     * @return array{
+     *     schema: string,
+     *     version: int,
+     *     supported_shapes: array<int, string>,
+     *     role_vocabulary: array<int, string>,
+     *     current_shape: string,
+     *     current_roles: array<int, string>,
+     *     execution_mode: string
+     * }
+     */
+    public static function info(): array
+    {
+        return [
+            'schema' => self::SCHEMA,
+            'version' => self::VERSION,
+            'supported_shapes' => self::SUPPORTED_SHAPES,
+            'role_vocabulary' => self::ROLE_VOCABULARY,
+            'current_shape' => 'standalone_server',
+            'current_roles' => self::CURRENT_SERVER_NODE_ROLES,
+            'execution_mode' => self::executionMode(),
+        ];
+    }
+
+    private static function executionMode(): string
+    {
+        return config('server.mode') === 'embedded'
+            ? 'local_queue_worker'
+            : 'remote_worker_protocol';
+    }
+}

tests/Feature/ClusterInfoCompatibilityTest.php

@@ -6,6 +6,7 @@
 use App\Support\ClientCompatibility;
 use App\Support\ControlPlaneProtocol;
 use App\Support\ControlPlaneRequestContract;
+use App\Support\ServerTopology;
 use App\Support\WorkerProtocol;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Tests\TestCase;
@@ -70,12 +71,23 @@ public function test_cluster_info_is_a_versionless_protocol_discovery_contract()
                     'max_pending_children',
                 ],
                 'structural_limits',
+                'topology' => [
+                    'schema',
+                    'version',
+                    'supported_shapes',
+                    'role_vocabulary',
+                    'current_shape',
+                    'current_roles',
+                    'execution_mode',
+                ],
                 'client_compatibility',
                 'auth_composition_contract',
                 'control_plane',
                 'worker_protocol',
                 'bridge_adapter_outcome_contract',
             ])
+            ->assertJsonPath('topology.schema', ServerTopology::SCHEMA)
+            ->assertJsonPath('topology.version', ServerTopology::VERSION)
             ->assertJsonPath('control_plane.version', ControlPlaneProtocol::VERSION)
             ->assertJsonPath('worker_protocol.version', WorkerProtocol::VERSION)
             ->assertJsonPath('client_compatibility.authority', 'protocol_manifests');

tests/Feature/ClusterInfoTest.php

@@ -2,6 +2,7 @@
 
 namespace Tests\Feature;
 
+use App\Support\ServerTopology;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Tests\TestCase;
 
@@ -135,6 +136,35 @@ public function test_it_publishes_external_task_input_contract_manifest(): void
             );
     }
 
+    public function test_it_publishes_role_topology_for_the_current_server_node(): void
+    {
+        $this->getJson('/api/cluster/info')
+            ->assertOk()
+            ->assertJsonPath('topology.schema', ServerTopology::SCHEMA)
+            ->assertJsonPath('topology.version', ServerTopology::VERSION)
+            ->assertJsonPath('topology.current_shape', 'standalone_server')
+            ->assertJsonPath('topology.execution_mode', 'remote_worker_protocol')
+            ->assertJsonPath('topology.current_roles.0', 'api_ingress')
+            ->assertJsonPath('topology.current_roles.1', 'control_plane')
+            ->assertJsonPath('topology.current_roles.2', 'matching')
+            ->assertJsonPath('topology.current_roles.3', 'history_projection')
+            ->assertJsonPath('topology.supported_shapes.0', 'embedded')
+            ->assertJsonPath('topology.supported_shapes.1', 'standalone_server')
+            ->assertJsonPath('topology.supported_shapes.2', 'split_control_execution')
+            ->assertJsonPath('topology.role_vocabulary.4', 'scheduler')
+            ->assertJsonPath('topology.role_vocabulary.5', 'execution_plane');
+    }
+
+    public function test_it_switches_cluster_topology_execution_mode_when_embedded_dispatch_is_enabled(): void
+    {
+        config(['server.mode' => 'embedded']);
+
+        $this->getJson('/api/cluster/info')
+            ->assertOk()
+            ->assertJsonPath('topology.current_shape', 'standalone_server')
+            ->assertJsonPath('topology.execution_mode', 'local_queue_worker');
+    }
+
     public function test_it_publishes_external_execution_surface_contract_manifest(): void
     {
         $this->getJson('/api/cluster/info')