Fail closed on undeclared metric dimensions

Fail closed on undeclared metric dimensions

Author: durable-workflow-ops

app/Support/BoundedMetricPolicy.php

@@ -2,6 +2,8 @@
 
 namespace App\Support;
 
+use InvalidArgumentException;
+
 final class BoundedMetricPolicy
 {
     /**
@@ -10,10 +12,26 @@ final class BoundedMetricPolicy
      */
     public static function labelSet(string $metric, array $runtimeDimensions = []): array
     {
-        $declared = config("dw-bounded-growth.metrics.{$metric}.dimensions", []);
+        $metrics = config('dw-bounded-growth.metrics', []);
+
+        if (! is_array($metrics) || ! array_key_exists($metric, $metrics)) {
+            throw new InvalidArgumentException("Metric {$metric} is missing from config/dw-bounded-growth.php.");
+        }
+
+        $declared = $metrics[$metric]['dimensions'] ?? null;
 
         if (! is_array($declared)) {
-            return $runtimeDimensions;
+            throw new InvalidArgumentException("Metric {$metric} must declare bounded-growth dimensions.");
+        }
+
+        $unknownDimensions = array_diff(array_keys($runtimeDimensions), array_keys($declared));
+
+        if ($unknownDimensions !== []) {
+            throw new InvalidArgumentException(sprintf(
+                'Metric %s disclosed undeclared runtime dimension(s): %s.',
+                $metric,
+                implode(', ', $unknownDimensions),
+            ));
         }
 
         $labelSet = [];

docs/bounded-growth.md

@@ -24,6 +24,9 @@ added without a TTL, admission, or cardinality contract.
 - Prometheus label names emitted by app code or the perf harness must exactly
   match the declared metric dimensions, so adding a label requires a reviewed
   cardinality policy in the same change.
+- Runtime metric cardinality disclosures must fail closed: a metric cannot
+  expose a label-set policy unless the metric and every disclosed dimension are
+  declared in `config/dw-bounded-growth.php`.
 - Remote-write scrape labels must stay deployment-scoped. Per-run values such
   as `GITHUB_RUN_ID` and `RUNNER_NAME` belong in `summary.json` provenance, not
   in Prometheus labels that create new series for every soak.
@@ -68,6 +71,8 @@ added without a TTL, admission, or cardinality contract.
   covered by a `metrics` entry;
 - Prometheus labels emitted by app or perf-harness source must exactly match
   the corresponding metric dimensions declared in the policy;
+- runtime metric disclosures reject unknown metrics or undeclared dimensions
+  before they can appear in `/api/system/metrics`;
 - perf-harness remote-write target labels must not include per-run or
   per-runner dimensions;
 - each policy entry must include the required review fields;

tests/Unit/BoundedMetricPolicyTest.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Tests\Unit;
+
+use App\Support\BoundedMetricPolicy;
+use InvalidArgumentException;
+use Tests\TestCase;
+
+class BoundedMetricPolicyTest extends TestCase
+{
+    public function test_label_set_rejects_metrics_without_bounded_growth_policy(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Metric dw_unreviewed_metric is missing from config/dw-bounded-growth.php.');
+
+        BoundedMetricPolicy::labelSet('dw_unreviewed_metric');
+    }
+
+    public function test_label_set_rejects_runtime_dimensions_missing_from_policy(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage(
+            'Metric dw_projection_drift_total disclosed undeclared runtime dimension(s): workflow_type.',
+        );
+
+        BoundedMetricPolicy::labelSet('dw_projection_drift_total', [
+            'table' => [
+                'values' => ['run_summaries'],
+            ],
+            'workflow_type' => [
+                'selection' => 'all',
+            ],
+        ]);
+    }
+
+    public function test_label_set_merges_declared_cardinality_policy_with_runtime_metadata(): void
+    {
+        $labelSet = BoundedMetricPolicy::labelSet('dw_projection_drift_total', [
+            'table' => [
+                'values' => ['run_summaries', 'run_waits'],
+                'selection' => 'fixed_projection_table_inventory',
+            ],
+        ]);
+
+        $this->assertSame([
+            'namespace' => 'server_scope_no_label',
+            'table' => [
+                'cardinality_class' => 'finite_projection_table_inventory',
+                'values' => ['run_summaries', 'run_waits'],
+                'selection' => 'fixed_projection_table_inventory',
+            ],
+        ], $labelSet);
+    }
+}