Scope selected run lookups by namespace

Author: durable-workflow-ops

src/V2/Support/HealthCheck.php

@@ -19,6 +19,7 @@ public static function snapshot(?CarbonInterface $now = null): array
             self::backendCheck($metrics['backend'] ?? []),
             self::runSummaryProjectionCheck($metrics['projections']['run_summaries'] ?? []),
             self::selectedRunProjectionCheck($metrics['projections'] ?? []),
+            self::commandContractCheck($metrics['command_contracts'] ?? []),
             self::taskTransportCheck($metrics['tasks'] ?? [], $metrics['backlog'] ?? []),
             self::durableResumePathCheck($metrics['backlog'] ?? [], $metrics['repair'] ?? []),
             self::workerCompatibilityCheck($metrics['workers'] ?? []),
@@ -144,6 +145,28 @@ private static function selectedRunProjectionCheck(array $projections): array
         );
     }
 
+    /**
+     * @param array<string, mixed> $metrics
+     * @return array<string, mixed>
+     */
+    private static function commandContractCheck(array $metrics): array
+    {
+        $needed = self::integer($metrics['backfill_needed_runs'] ?? 0);
+
+        return self::check(
+            'command_contract_snapshots',
+            $needed === 0 ? 'ok' : 'warning',
+            $needed === 0
+                ? 'WorkflowStarted command-contract snapshots are complete.'
+                : 'Some WorkflowStarted command-contract snapshots need backfill before operators can trust command forms.',
+            [
+                'backfill_needed_runs' => $needed,
+                'backfill_available_runs' => self::integer($metrics['backfill_available_runs'] ?? 0),
+                'backfill_unavailable_runs' => self::integer($metrics['backfill_unavailable_runs'] ?? 0),
+            ],
+        );
+    }
+
     /**
      * @param array<string, mixed> $tasks
      * @param array<string, mixed> $backlog

src/V2/Support/HistoryExport.php

@@ -57,6 +57,8 @@ public static function forRun(
             'childLinks',
         ]);
 
+        RunCommandContract::forRun($run);
+
         $summary = $run->summary;
         $selectedRun = SelectedRunSnapshot::forRun($run);
         $currentRunResolution = $selectedRun['current_run'];

src/V2/Support/OperatorMetrics.php

@@ -10,6 +10,7 @@
 use Workflow\V2\Enums\CommandOutcome;
 use Workflow\V2\Enums\CommandStatus;
 use Workflow\V2\Enums\CommandType;
+use Workflow\V2\Enums\HistoryEventType;
 use Workflow\V2\Enums\RunStatus;
 use Workflow\V2\Enums\TaskStatus;
 use Workflow\V2\Enums\TaskType;
@@ -43,6 +44,7 @@ public static function snapshot(?CarbonInterface $now = null): array
             'repair' => TaskRepairCandidates::snapshot($now),
             'starts' => self::startMetrics($now),
             'history' => self::historyMetrics(),
+            'command_contracts' => self::commandContractMetrics(),
             'projections' => self::projectionMetrics(),
             'workers' => self::workerMetrics(),
             'backend' => BackendCapabilities::snapshot($now),
@@ -213,6 +215,51 @@ private static function historyMetrics(): array
         ];
     }
 
+    /**
+     * @return array<string, int>
+     */
+    private static function commandContractMetrics(): array
+    {
+        $needed = 0;
+        $available = 0;
+
+        self::runModel()::query()
+            ->whereHas('historyEvents', static function ($query): void {
+                $query->where('event_type', HistoryEventType::WorkflowStarted->value);
+            })
+            ->with([
+                'historyEvents' => static function ($query): void {
+                    $query->where('event_type', HistoryEventType::WorkflowStarted->value)
+                        ->orderBy('sequence');
+                },
+            ])
+            ->chunkById(200, static function ($runs) use (&$needed, &$available): void {
+                foreach ($runs as $run) {
+                    if (! $run instanceof WorkflowRun) {
+                        continue;
+                    }
+
+                    $status = RunCommandContract::backfillStatus($run);
+
+                    if (! $status['needed']) {
+                        continue;
+                    }
+
+                    $needed++;
+
+                    if ($status['available']) {
+                        $available++;
+                    }
+                }
+            });
+
+        return [
+            'backfill_needed_runs' => $needed,
+            'backfill_available_runs' => $available,
+            'backfill_unavailable_runs' => max(0, $needed - $available),
+        ];
+    }
+
     /**
      * @return array<string, array<string, int|string|null>>
      */