fix(resource-contract-telemetry): remediate #26 review — real observe-mode bug + validator teeth

MANIFEST.txt

@@ -124,6 +124,7 @@ tools/tests/test_manifest.py
 tools/tests/test_mesh_consume.py
 tools/tests/test_model_fabric_release_readiness.py
 tools/tests/test_operational_exhaust_fusion.py
+tools/tests/test_resource_contract_verdict.py
 tools/tests/test_serve.py
 tools/tests/test_service_desk_metrics.py
 tools/validate_client_runtime_dump_exposure.py

docs/devops/resource-contract-telemetry.md

@@ -29,14 +29,22 @@ so the loop speaks one language end to end:
 | condition | verdict | meaning |
 |---|---|---|
 | `enforcement != observe` and `fired_count > 0` and peak gate-eligible | **PROVED** | the control has been observed to act on real load |
-| `observedPeak.value > limit.value` and `fired_count == 0` | **VIOLATION** | never-fired control — a counterexample to the claim it is a control |
+| `enforcement != observe` and `observedPeak.value > limit.value` and `fired_count == 0` | **VIOLATION** | never-fired control — a counterexample to the claim it is a control |
 | peak not gate-eligible (`source != measured` or `unobserved > 0`) | **INCONCLUSIVE** | sufficiency unestablished; no verdict on the control can be drawn |
+| `enforcement == observe` and `observedPeak.value > limit.value` | **INCONCLUSIVE** | a declared gauge, not a gate — no teeth-claim to prove or violate |
 
-The **VIOLATION** row is the load-bearing one. A limit exceeded in production that never once
-enforced is not an absence of news — it is evidence the control is paper. The normalization rule
-`never_fired_control_is_a_violation` forbids dropping it, summarizing it to a healthy counter, or
-downgrading it to INCONCLUSIVE: the exceedance was *measured*, so sufficiency is not the question,
-enforcement is.
+The **VIOLATION** row is the load-bearing one. A limit that *claimed teeth* and was exceeded in
+production yet never once enforced is not an absence of news — it is evidence the control is
+paper. The rule `never_fired_control_is_a_violation` forbids dropping it, summarizing it to a
+healthy counter, or downgrading it to INCONCLUSIVE.
+
+The `enforcement != observe` guard on that row is itself load-bearing. VIOLATION is a **broken
+enforcement promise**, and `observe` mode makes no promise — it is the honest, declared "gauge,
+not gate" (ResourceContract requires an `observeOnlyReason` for it). An observe-mode exceedance is
+therefore **INCONCLUSIVE**, per `observe_mode_exceedance_is_inconclusive_not_violation`: flagging
+it VIOLATION would accuse a gauge of failing to be a gate and punish honest declaration. The
+exceedance is never hidden either way — it flows as a `resource-saturation` TelemetrySignal
+regardless of verdict, so an operator can still decide to promote the gauge to an enforcing limit.
 
 ## Canonical objects and topics
 

mappings/resource-contract-measurement-telemetry-v1.yaml

@@ -93,12 +93,17 @@ canonical_objects:
         enforcement != observe AND fired_count > 0 AND the observed peak is gate-eligible —
         the control has been observed to act on real load.
       VIOLATION: >-
-        observed_peak.value > limit.value AND fired_count == 0 — the limit was exceeded in
-        production and never once enforced. A never-fired control is a counterexample to the
-        claim that it is a control, not the absence of one.
+        enforcement != observe AND observed_peak.value > limit.value AND fired_count == 0 — a
+        control that CLAIMED teeth (throttle/refuse/terminate) was exceeded in production and
+        never once enforced. A never-fired control is a counterexample to the claim that it is
+        a control, not the absence of one. The enforcement != observe guard is load-bearing:
+        VIOLATION is a broken ENFORCEMENT PROMISE, and observe mode makes no such promise.
       INCONCLUSIVE: >-
         the observed peak is not gate-eligible (measurement_source != measured, or members were
-        unobserved) — sufficiency is not established, so no verdict on the control can be drawn.
+        unobserved), OR the contract is observe-mode — a declared gauge, not a gate, which makes
+        no teeth-claim to prove or violate. In neither case can a verdict on enforcement teeth
+        be drawn. The exceedance itself is never hidden: it still flows as a resource-saturation
+        TelemetrySignal regardless of verdict.
 
 normalization_rules:
   - id: carry_gate_eligibility_unrecomputed
@@ -108,10 +113,23 @@ normalization_rules:
       that owns the instrument; a consumer may lower it but never raise it.
   - id: never_fired_control_is_a_violation
     rule: >-
-      A ResourceContract whose observed peak exceeds its limit while fired_count is zero MUST
-      normalize to a SufficiencyVerdict of VIOLATION and be published to ops.learning.feedback.v1.
-      It MUST NOT be dropped, summarized to a healthy counter, or downgraded to INCONCLUSIVE —
-      the exceedance was measured, so sufficiency is not the question; enforcement is.
+      A ResourceContract whose enforcement is not observe, whose observed peak exceeds its limit,
+      and whose fired_count is zero MUST normalize to a SufficiencyVerdict of VIOLATION and be
+      published to ops.learning.feedback.v1. It MUST NOT be dropped, summarized to a healthy
+      counter, or downgraded to INCONCLUSIVE — the exceedance was measured and enforcement was
+      claimed, so the broken promise is the finding. The enforcement != observe qualifier is
+      required: an observe-mode contract makes no enforcement promise and so cannot violate one
+      (see observe_mode_exceedance_is_inconclusive_not_violation); its exceedance still flows as
+      telemetry, but yields no teeth-verdict.
+  - id: observe_mode_exceedance_is_inconclusive_not_violation
+    rule: >-
+      A ResourceContract with enforcement == observe whose observed peak exceeds its limit MUST
+      normalize to INCONCLUSIVE, never VIOLATION. Observe mode is the honest, declared "gauge not
+      gate" (ResourceContract requires an observeOnlyReason for it). Marking it VIOLATION would
+      accuse a gauge of failing to be a gate and would punish honest declaration — training the
+      learning loop to demand fixes for things explicitly declared not-controls. The exceedance
+      is still published as a resource-saturation TelemetrySignal so an operator can decide
+      whether to promote the gauge to an enforcing limit.
   - id: unmeasured_peak_is_inconclusive_not_healthy
     rule: >-
       A ResourceContract whose observed peak is not gate-eligible MUST normalize to INCONCLUSIVE,

tools/tests/test_resource_contract_verdict.py

@@ -0,0 +1,92 @@
+"""Teeth tests for the ResourceContract/Measurement verdict algebra.
+
+The verdict function `expected_verdict` in tools/validate_resource_contract_telemetry.py is the
+correctness core of the whole profile — it decides PROVED / VIOLATION / INCONCLUSIVE, which is
+what sociosphere's learning loop consumes. On first review that function shipped with a real
+precedence bug: an observe-mode contract that exceeded its limit was returned as VIOLATION, which
+accuses a declared gauge of failing to be a gate. It went unnoticed because the algebra was only
+exercised indirectly by the validator script's own example, never in the pytest suite.
+
+These tests pin every precedence branch in `make test`, so a regression is caught even if the
+worked example file changes. Each case names the input axis it isolates.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[2]
+VALIDATOR = ROOT / "tools" / "validate_resource_contract_telemetry.py"
+
+
+def _load():
+    spec = importlib.util.spec_from_file_location("rc_telemetry_validator", VALIDATOR)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+expected_verdict = _load().expected_verdict
+
+
+# A gate-eligible, exceeded, never-fired throttle contract — the canonical VIOLATION.
+BASE = dict(
+    peak_value=0.94, limit_value=0.5, fired_count=0, gate_eligible=True, enforcement="throttle",
+)
+
+
+def test_canonical_violation():
+    """A throttle that was exceeded and never fired is a broken enforcement promise."""
+    assert expected_verdict(**BASE) == "VIOLATION"
+
+
+def test_gate_ineligible_wins_first():
+    """An unmeasured/partial peak cannot certify anything — INCONCLUSIVE outranks everything,
+    even an apparent exceedance."""
+    assert expected_verdict(**{**BASE, "gate_eligible": False}) == "INCONCLUSIVE"
+
+
+def test_enforcement_acted_is_proved():
+    """A control that claimed teeth and was observed to fire on real load."""
+    assert expected_verdict(**{**BASE, "fired_count": 3}) == "PROVED"
+
+
+def test_within_limit_is_inconclusive():
+    """No exceedance, nothing fired: no counterexample and no teeth proven. No news is not
+    proof of teeth."""
+    assert expected_verdict(**{**BASE, "peak_value": 0.10}) == "INCONCLUSIVE"
+
+
+def test_observe_mode_exceedance_is_inconclusive_not_violation():
+    """The bug this module exists to pin. An observe-mode contract makes NO enforcement promise,
+    so an exceedance cannot violate one. It must be INCONCLUSIVE, never VIOLATION."""
+    assert expected_verdict(**{**BASE, "enforcement": "observe"}) == "INCONCLUSIVE"
+
+
+def test_observe_mode_never_proves_teeth():
+    """Even if an observe-mode contract shows fired_count > 0 (it should not, but defensively),
+    observe mode cannot PROVE enforcement teeth — it isn't an enforcing mode."""
+    assert expected_verdict(**{**BASE, "enforcement": "observe", "fired_count": 5}) != "PROVED"
+
+
+@pytest.mark.parametrize("mode", ["throttle", "refuse", "terminate"])
+def test_all_enforcing_modes_violate_when_exceeded_and_unfired(mode):
+    """The VIOLATION rule applies to every mode that claims teeth, not just throttle."""
+    assert expected_verdict(**{**BASE, "enforcement": mode}) == "VIOLATION"
+
+
+def test_verdict_is_always_one_of_three():
+    """The algebra is total: every input shape yields exactly one of the three verdicts."""
+    verdicts = {
+        expected_verdict(
+            peak_value=p, limit_value=0.5, fired_count=f, gate_eligible=g, enforcement=e
+        )
+        for p in (0.10, 0.94)
+        for f in (0, 3)
+        for g in (True, False)
+        for e in ("observe", "throttle", "refuse", "terminate")
+    }
+    assert verdicts <= {"PROVED", "VIOLATION", "INCONCLUSIVE"}