Surface matching-role shape on dw system:operator-metrics

Declares operator_metrics.matching_role in the CLI output schema and
renders queue_wake_enabled, shape, and task_dispatch_mode on a
dedicated "Matching-role (this node)" section with a graceful fallback
when the server does not emit the block. The block is per-process and
the renderer labels the scope so operators in mixed-shape fleets
understand one snapshot reflects one node.

Author: durable-workflow-ops

schemas/output/operator-metrics.schema.json

@@ -118,6 +118,15 @@
             "failure_backoff_max_seconds": { "type": ["integer", "null"] }
           },
           "additionalProperties": true
+        },
+        "matching_role": {
+          "type": "object",
+          "properties": {
+            "queue_wake_enabled": { "type": ["boolean", "null"] },
+            "shape": { "type": ["string", "null"] },
+            "task_dispatch_mode": { "type": ["string", "null"] }
+          },
+          "additionalProperties": true
         }
       },
       "additionalProperties": true

src/Commands/SystemCommand/OperatorMetricsCommand.php

@@ -38,8 +38,11 @@ protected function configure(): void
   <info>dw system:operator-metrics --json | jq '.operator_metrics.workers'</info>
 
 The contract guarantees the frozen key inventory under
-`operator_metrics.{runs,tasks,backlog,repair,workers,backend,schedules,repair_policy}`;
-consumers MAY add derived keys but MUST NOT rename these.
+`operator_metrics.{runs,tasks,backlog,repair,workers,backend,schedules,repair_policy,matching_role}`;
+consumers MAY add derived keys but MUST NOT rename these. The
+`matching_role` block is per-process and reflects only the node
+serving the request; read one snapshot per node to see the full
+deployment shape.
 HELP)
             ->addOption('json', null, InputOption::VALUE_NONE, 'Output as JSON');
     }
@@ -68,6 +71,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $this->renderRepair($output, $this->sectionArray($metrics, 'repair'));
         $this->renderWorkers($output, $this->sectionArray($metrics, 'workers'));
         $this->renderBackend($output, $this->sectionArray($metrics, 'backend'));
+        $this->renderMatchingRole($output, $this->sectionArray($metrics, 'matching_role'));
         $this->renderSchedules($output, $this->sectionArray($metrics, 'schedules'));
         $this->renderRepairPolicy($output, $this->sectionArray($metrics, 'repair_policy'));
 
@@ -287,6 +291,35 @@ private function renderBackend(OutputInterface $output, array $backend): void
         $output->writeln('');
     }
 
+    /**
+     * @param  array<string, mixed>  $matchingRole
+     */
+    private function renderMatchingRole(OutputInterface $output, array $matchingRole): void
+    {
+        if ($matchingRole === []) {
+            return;
+        }
+
+        $output->writeln('<info>Matching-role (this node)</info>');
+
+        if (array_key_exists('queue_wake_enabled', $matchingRole)) {
+            $output->writeln(sprintf(
+                '  Queue wake enabled:   %s',
+                ((bool) $matchingRole['queue_wake_enabled']) ? 'yes' : 'no',
+            ));
+        }
+
+        if (is_string($matchingRole['shape'] ?? null) && $matchingRole['shape'] !== '') {
+            $output->writeln(sprintf('  Shape:                %s', $matchingRole['shape']));
+        }
+
+        if (is_string($matchingRole['task_dispatch_mode'] ?? null) && $matchingRole['task_dispatch_mode'] !== '') {
+            $output->writeln(sprintf('  Task dispatch mode:   %s', $matchingRole['task_dispatch_mode']));
+        }
+
+        $output->writeln('');
+    }
+
     /**
      * @param  array<string, mixed>  $schedules
      */

tests/Commands/SystemCommandTest.php

@@ -549,6 +549,11 @@ public function test_operator_metrics_command_renders_rollout_safety_signals():
         self::assertStringContainsString('Database:              mysql/mysql', $display);
         self::assertStringContainsString('Cache:                 redis/redis', $display);
 
+        self::assertStringContainsString('Matching-role (this node)', $display);
+        self::assertStringContainsString('Queue wake enabled:   yes', $display);
+        self::assertStringContainsString('Shape:                in_worker', $display);
+        self::assertStringContainsString('Task dispatch mode:   queue', $display);
+
         self::assertStringContainsString('Active 4, paused 1, missed 1, oldest overdue 5000 ms', $display);
         self::assertStringContainsString('Lifetime fires: 128 (3 failures)', $display);
 
@@ -668,6 +673,43 @@ public function test_operator_metrics_schema_pins_run_wait_age_keys(): void
         self::assertSame(['integer', 'null'], $runs['max_wait_age_ms']['type']);
     }
 
+    public function test_operator_metrics_schema_pins_matching_role_keys(): void
+    {
+        $schema = json_decode(
+            (string) file_get_contents(__DIR__.'/../../schemas/output/operator-metrics.schema.json'),
+            true,
+            flags: JSON_THROW_ON_ERROR,
+        );
+
+        $matchingRole = $schema['properties']['operator_metrics']['properties']['matching_role']['properties'];
+
+        self::assertSame(['boolean', 'null'], $matchingRole['queue_wake_enabled']['type']);
+        self::assertSame(['string', 'null'], $matchingRole['shape']['type']);
+        self::assertSame(['string', 'null'], $matchingRole['task_dispatch_mode']['type']);
+    }
+
+    public function test_operator_metrics_command_renders_dedicated_matching_role_shape(): void
+    {
+        $payload = self::operatorMetricsPayload();
+        $payload['operator_metrics']['matching_role'] = [
+            'queue_wake_enabled' => false,
+            'shape' => 'dedicated',
+            'task_dispatch_mode' => 'poll',
+        ];
+
+        $command = new OperatorMetricsCommand();
+        $command->setServerClient(new SystemFakeClient($payload));
+
+        $tester = new CommandTester($command);
+        self::assertSame(Command::SUCCESS, $tester->execute([]));
+
+        $display = $tester->getDisplay();
+
+        self::assertStringContainsString('Queue wake enabled:   no', $display);
+        self::assertStringContainsString('Shape:                dedicated', $display);
+        self::assertStringContainsString('Task dispatch mode:   poll', $display);
+    }
+
     public function test_operator_metrics_command_tolerates_minimal_payload(): void
     {
         $command = new OperatorMetricsCommand();
@@ -781,6 +823,11 @@ private static function operatorMetricsPayload(): array
                     'scan_limit' => 100,
                     'failure_backoff_max_seconds' => 300,
                 ],
+                'matching_role' => [
+                    'queue_wake_enabled' => true,
+                    'shape' => 'in_worker',
+                    'task_dispatch_mode' => 'queue',
+                ],
             ],
         ];
     }