Expose matching-role partition and backpressure metadata in operator metrics

Surface matching-role routing metadata in operator metrics

Author: durable-workflow-ops

docs/architecture/task-matching.md

@@ -441,14 +441,20 @@ layer healthy" without reading task rows directly:
   `leased_tasks`, `retrying_activities`, `unhealthy_tasks`,
   `claim_failed_runs`, and `compatibility_blocked_runs`; a
   `workers` block with the Phase 2 compatibility roll-up; and a
-  `matching_role` block with `queue_wake_enabled`, `shape`, and
-  `task_dispatch_mode`. `shape` is `in_worker` when this process
+  `matching_role` block with `queue_wake_enabled`, `shape`,
+  `task_dispatch_mode`, `partition_primitives`, and
+  `backpressure_model`. `shape` is `in_worker` when this process
   still runs the in-worker broad-poll wake and `dedicated` when
   the process has opted out so the broad sweep runs under
-  `php artisan workflow:v2:repair-pass`. The snapshot reports the
-  configuration observed by the process serving the request; in
-  mixed-shape fleets, operators read one snapshot per node to see
-  the full deployment.
+  `php artisan workflow:v2:repair-pass`. `partition_primitives`
+  freezes the routing axes in order:
+  `connection`, `queue`, `compatibility`, `namespace`.
+  `backpressure_model` reports `lease_ownership`, meaning the durable
+  admission boundary is lease occupancy and lease expiry rather
+  than an engine-enforced per-worker quota. The snapshot reports
+  the configuration observed by the process serving the request;
+  in mixed-shape fleets, operators read one snapshot per node to
+  see the full deployment.
 - `Workflow\V2\Support\OperatorQueueVisibility::forNamespace()` /
   `::forQueue()` returns per-partition queue depth, leased depth,
   poller heartbeats, and stale-worker detection.

src/V2/Support/MatchingRoleSnapshot.php

@@ -16,8 +16,18 @@ final class MatchingRoleSnapshot
      * opted out and the broad sweep is expected to run as
      * `php artisan workflow:v2:repair-pass` instead. `task_dispatch_mode`
      * reports the configured dispatch mode (`queue` or `poll`).
+     * `partition_primitives` freezes the matching-role routing axes that
+     * operators and downstream clients can reason about, while
+     * `backpressure_model` reports the durable admission boundary the
+     * engine enforces today.
      *
-     * @return array{queue_wake_enabled: bool, shape: string, task_dispatch_mode: string}
+     * @return array{
+     *     queue_wake_enabled: bool,
+     *     shape: string,
+     *     task_dispatch_mode: string,
+     *     partition_primitives: list<string>,
+     *     backpressure_model: string
+     * }
      */
     public static function current(): array
     {
@@ -31,6 +41,8 @@ public static function current(): array
             'queue_wake_enabled' => $queueWakeEnabled,
             'shape' => $queueWakeEnabled ? 'in_worker' : 'dedicated',
             'task_dispatch_mode' => $dispatchMode,
+            'partition_primitives' => ['connection', 'queue', 'compatibility', 'namespace'],
+            'backpressure_model' => 'lease_ownership',
         ];
     }
 }

tests/Feature/V2/V2OperatorMetricsTest.php

@@ -2246,6 +2246,8 @@ public function testSnapshotReportsInWorkerMatchingRoleShapeByDefault(): void
                 'queue_wake_enabled' => true,
                 'shape' => 'in_worker',
                 'task_dispatch_mode' => 'queue',
+                'partition_primitives' => ['connection', 'queue', 'compatibility', 'namespace'],
+                'backpressure_model' => 'lease_ownership',
             ],
             $snapshot['matching_role'],
         );
@@ -2264,6 +2266,8 @@ public function testSnapshotReportsDedicatedMatchingRoleShapeWhenQueueWakeIsDisa
                 'queue_wake_enabled' => false,
                 'shape' => 'dedicated',
                 'task_dispatch_mode' => 'poll',
+                'partition_primitives' => ['connection', 'queue', 'compatibility', 'namespace'],
+                'backpressure_model' => 'lease_ownership',
             ],
             $snapshot['matching_role'],
         );

tests/Unit/Commands/V2DoctorCommandTest.php

@@ -41,7 +41,7 @@ public function testJsonOutputIncludesTheMatchingRoleShape(): void
             '--json' => true,
         ])
             ->expectsOutputToContain(
-                '"matching_role":{"queue_wake_enabled":false,"shape":"dedicated","task_dispatch_mode":"poll"}'
+                '"matching_role":{"queue_wake_enabled":false,"shape":"dedicated","task_dispatch_mode":"poll","partition_primitives":["connection","queue","compatibility","namespace"],"backpressure_model":"lease_ownership"}'
             )
             ->assertSuccessful();
     }

tests/Unit/V2/TaskMatchingDocumentationTest.php

@@ -412,7 +412,14 @@ public function testContractDocumentExposesMatchingRoleShapeOnOperatorSnapshot()
     {
         $contents = $this->documentContents();
 
-        foreach (['`matching_role`', '`queue_wake_enabled`', '`shape`', '`task_dispatch_mode`'] as $field) {
+        foreach ([
+            '`matching_role`',
+            '`queue_wake_enabled`',
+            '`shape`',
+            '`task_dispatch_mode`',
+            '`partition_primitives`',
+            '`backpressure_model`',
+        ] as $field) {
             $this->assertStringContainsString(
                 $field,
                 $contents,
@@ -433,6 +440,12 @@ public function testContractDocumentExposesMatchingRoleShapeOnOperatorSnapshot()
                 ),
             );
         }
+
+        $this->assertStringContainsString(
+            '`lease_ownership`',
+            $contents,
+            'Task matching contract must name the lease_ownership backpressure model so operator surfaces can expose the durable admission boundary without paraphrasing it.',
+        );
     }
 
     private function documentContents(): string