feat(ops): publish ADR 0114's degraded gauge on /status, /metrics and the console

AC-7 requires "a WARNING naming the reason + degraded gauge", and §4's
compensating-control story assumes an operator can SEE the degraded state. Nobody
could: claim_proc_effective / claim_proc_degraded_reason were read by the store's
own tests and nothing else — no /stats, no /status, no /metrics, no console. The
whole operator signal was one WARNING at open(), in a log nobody was watching,
that until PR #86 named the wrong cause. That is a load-bearing part of why the
lever could sit inert in every deployment for its entire life.

Surfaces the store's claim_proc_status() on:

  * GET /status  -> claim_proc: effective, the human-readable degraded_reason,
                    and the matched head_forms
  * GET /metrics -> messagefoundry_store_claim_proc_effective and
                    messagefoundry_store_claim_proc_head_verbatim
  * /ui/status   -> store-panel rows

Three shape decisions. The field/series are ABSENT, not 0/false, when the lever
was never requested: a constant 0 on every SQLite fleet is unalertable noise, and
absence keeps "not requested" distinct from "requested and degraded". No reason
LABEL in the exposition — the reason is free text embedding a proc name and, on
the probe-failure arm, an exception string, so a label would be unbounded
cardinality and a breach of the exporter's strict {connection, destination,
status, version, le} allowlist; the string goes to /status and the console. And it
deliberately does NOT feed the console's engine-health heart: claims keep flowing
on the batch, so a degrade is a lever not paying off, not an unwell store, and
making the nav cry wolf would devalue the signal that means it is.

head_forms is surfaced for the same reason it is logged: a fleet reporting
"verbatim" is a live counterexample to _CLAIM_PROC_STORED_HEADS's compatibility
assumption, and was previously visible only at INFO.

Observability only — the gate's accept/degrade logic is untouched. The new tests
assert the rendered output of each surface, not the existence of a property.

Rendering a new SystemStatus field on the console is a seam change, so
ENGINE_UI_SEAM and the console's SUPPORTED_ENGINE_SEAMS both move to 16 and the
golden snapshot is refreshed. A separate seam rather than a correction to the
unreleased v15: v15 is a SecurityPosture change, and folding an unrelated DTO into
it would make that note describe a field set it does not cover.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: wshallwshall

messagefoundry/api/_ui_seam.py

@@ -75,7 +75,13 @@
 #: so an older console simply ignores it; bumped rather than corrected in place because v14 SHIPPED
 #: (v0.3.2). Under "one shipped posture, loosen only" a subset that reads as the whole posture is the
 #: failure this field exists to prevent, so the console must be able to render the caveat.
-ENGINE_UI_SEAM: int = 15
+#: seam v16: SystemStatus gained the additive `claim_proc` — ADR 0114 AC-7's degraded gauge (whether the
+#: SQL Server stored-procedure claim path passed its startup gate, and the reason string when it did
+#: not), which the status page's store panel renders. Additive with a default and `None` on every
+#: backend without the lever, so an older console simply ignores it; a separate seam rather than a
+#: correction to v15 because v15 is a SecurityPosture change and folding an unrelated DTO into it would
+#: make that note describe a field set it does not cover.
+ENGINE_UI_SEAM: int = 16
 
 
 @dataclass(frozen=True, slots=True)

messagefoundry/api/app.py

@@ -83,6 +83,7 @@
     CapturedResponseInfo,
     ChannelInfo,
     ClaimPoolInfo,
+    ClaimProcInfo,
     ClusterNode,
     ClusterNodeList,
     ClusterStatus,
@@ -4477,6 +4478,21 @@ async def system_status(
             if pool_status is not None
             else None
         )
+        # ADR 0114 AC-7's degraded gauge. Until this field existed the ONLY signal that the proc
+        # claim path had fallen back to the shipped batch was a WARNING at store open — which is a
+        # load-bearing part of why the gate could degrade in every deployment unnoticed. None unless
+        # [store].fifo_claim_proc is on and the backend has the lever, so the payload is unchanged
+        # by default. Synchronous + free (attributes the gate recorded once at open).
+        cps = engine.store.claim_proc_status()
+        claim_proc = (
+            ClaimProcInfo(
+                effective=cps.effective,
+                degraded_reason=cps.degraded_reason,
+                head_forms=dict(cps.head_forms),
+            )
+            if cps is not None
+            else None
+        )
         # App-log disk metering (#50), alongside the DB metrics — only when a log dir is configured.
         # Run the blocking stat()s off the event loop (the DB metering is itself off-loop in the store);
         # None when stdout-only or the directory is unreadable, so /status never raises on it.
@@ -4520,6 +4536,7 @@ async def system_status(
             logs=logs,
             update=update,
             pool=pool,
+            claim_proc=claim_proc,
         )
 
     # --- runtime log verbosity + redacted log-tail viewer (BACKLOG #171, ADR 0130) ----

messagefoundry/api/metrics.py

@@ -38,7 +38,12 @@
 
 from messagefoundry import __version__
 from messagefoundry.store.pool_metrics import PoolStatus
-from messagefoundry.store.store import DestinationMetrics, InboundMetrics, LatencyHistogram
+from messagefoundry.store.store import (
+    ClaimProcStatus,
+    DestinationMetrics,
+    InboundMetrics,
+    LatencyHistogram,
+)
 
 if TYPE_CHECKING:  # avoid pulling the heavy engine import into the default path
     from messagefoundry.pipeline import Engine
@@ -192,6 +197,10 @@ class _Snapshot:
     pool: PoolStatus | None = None
     committed_txns: int = 0
     body_copies: int = 0
+    # ADR 0114 AC-7's degraded gauge. None when the backend has no fifo_claim_proc lever or the flag
+    # is off — the gauges are then ABSENT rather than 0, so a scrape can tell "not requested" from
+    # "requested and degraded" (a constant 0 on every SQLite fleet would be pure alert noise).
+    claim_proc: ClaimProcStatus | None = None
 
 
 async def gather_snapshot(engine: Engine) -> _Snapshot:
@@ -230,6 +239,7 @@ async def gather_snapshot(engine: Engine) -> _Snapshot:
         pool=pool,
         committed_txns=committed_txns,
         body_copies=body_copies,
+        claim_proc=engine.store.claim_proc_status(),
     )
 
 
@@ -369,6 +379,33 @@ def collect(self) -> Iterable[Any]:
         body_copies.add_metric([], float(s.body_copies))
         yield body_copies
 
+        # ADR 0114 AC-7 degraded gauge. Emitted ONLY when [store].fifo_claim_proc is on: a constant
+        # 0 on every fleet that never asked for the lever is noise a scraper cannot alert on, and
+        # absence is the honest encoding of "not applicable here". Numeric and LABEL-LESS by
+        # design — the human-readable degrade reason is free text (it embeds a proc name and, on the
+        # probe-failure arm, an exception string), so carrying it as a label would both blow the
+        # cardinality budget and break this module's strict {connection,destination,status,version,le}
+        # allowlist. The reason string lives on /status and the console store panel instead.
+        cp = s.claim_proc
+        if cp is not None:
+            effective = GaugeMetricFamily(
+                "messagefoundry_store_claim_proc_effective",
+                "1 when the ADR 0114 stored-procedure claim path passed its startup gate and is"
+                " active, 0 when it degraded to the shipped ad-hoc batch (claims still flow).",
+            )
+            effective.add_metric([], 1.0 if cp.effective else 0.0)
+            yield effective
+            # Which stored head form the deployed modules matched. "verbatim" means this server did
+            # NOT rewrite the CREATE OR ALTER head — no engine measured to date does, so a fleet
+            # reporting 1 here is a live counterexample worth knowing about, not a fault.
+            verbatim = GaugeMetricFamily(
+                "messagefoundry_store_claim_proc_head_verbatim",
+                "1 when at least one deployed claim procedure's stored definition kept the CREATE"
+                " OR ALTER head verbatim (this server does not rewrite it), else 0.",
+            )
+            verbatim.add_metric([], 1.0 if "verbatim" in cp.head_forms.values() else 0.0)
+            yield verbatim
+
         # Connection-pool saturation + acquire-wait (server backends only; absent on SQLite, which has
         # no pool). [store].pool_size previously emitted NO saturation metric — these close that gap.
         pool = s.pool

messagefoundry/api/models.py

@@ -710,6 +710,26 @@ class PoolInfo(BaseModel):
     claim_pool: ClaimPoolInfo | None = None
 
 
+class ClaimProcInfo(BaseModel):
+    """The ADR 0114 sub-lever A (``fifo_claim_proc``) startup-gate verdict — AC-7's **degraded
+    gauge**, surfaced as the additive ``claim_proc`` field on :class:`SystemStatus`.
+
+    ``None`` on every backend without the lever and on SQL Server when the flag is off, so "not
+    requested" reads differently from "requested and degraded". When ``effective`` is False,
+    ``degraded_reason`` says why the store fell back to the shipped ad-hoc batch — claims keep
+    flowing either way, so this is a performance-lever gauge, not a health alarm.
+
+    Metadata only: proc names, a head-form word, and the gate's own reason string — no message
+    content and no PHI."""
+
+    effective: bool  # the gate passed; pooled claims run through the procs
+    degraded_reason: str | None = None  # why it degraded to the batch; None when effective
+    # proc name -> the stored head form the deployed module matched ("rewritten" | "verbatim").
+    # "verbatim" means this server does NOT rewrite CREATE OR ALTER — no engine measured to date
+    # does, so it is worth reporting; it is an engine difference, not a fault.
+    head_forms: dict[str, str] = Field(default_factory=dict)
+
+
 class SystemStatus(BaseModel):
     engine: EngineInfo
     # Engine-wide top-line roll-up KPIs (#93): total messages, combined in+out connection count with
@@ -727,6 +747,10 @@ class SystemStatus(BaseModel):
     # percentiles + size/idle occupancy). Additive + ``None`` on SQLite (no pool) so the existing
     # payload is unchanged on the default backend and an older client deserializes /status unchanged.
     pool: PoolInfo | None = None
+    # ADR 0114 AC-7's degraded gauge: whether the SQL Server proc claim path is effectively active,
+    # and why not when it isn't. Additive + ``None`` on every backend without the lever and whenever
+    # [store].fifo_claim_proc is off, so the default payload is unchanged.
+    claim_proc: ClaimProcInfo | None = None
 
 
 class IntegrityResult(BaseModel):

messagefoundry_webconsole/__init__.py

@@ -45,7 +45,7 @@
 # If cross-seam support is ever genuinely wanted, re-widen this set AND add the CI matrix that
 # installs the MIN and MAX supported engine builds — the claim and its test land together, or not
 # at all.
-SUPPORTED_ENGINE_SEAMS: frozenset[int] = frozenset({15})
+SUPPORTED_ENGINE_SEAMS: frozenset[int] = frozenset({16})
 
 #: The vendored static assets shipped in THIS wheel (mounted at /ui/static by :func:`mount_ui`).
 STATIC_DIR = Path(__file__).parent / "static"

messagefoundry_webconsole/pages/monitoring.py

@@ -352,6 +352,30 @@ def status(
         ],
         adjustable=False,
     )
+    # ADR 0114 AC-7's degraded gauge, on the panel an operator actually reads. Empty unless
+    # [store].fifo_claim_proc is on (SQL Server only), so the default page is unchanged — no blank
+    # row, no "—" that would read as a broken lever. A degrade is NOT an engine-health fault: claims
+    # keep flowing on the shipped batch, so it stays a row here and deliberately does not feed the
+    # nav heart, which would then cry wolf about a performance lever merely not paying off.
+    # Metadata only: proc names, a head-form word, and the gate's own reason string.
+    claim_proc_rows: list[list[object]] = []
+    cp = sys.claim_proc
+    if cp is not None:
+        claim_proc_rows.append(
+            [
+                "Claim path (ADR 0114 stored procedures)",
+                "active" if cp.effective else "DEGRADED — running the shipped batch",
+            ]
+        )
+        if not cp.effective:
+            claim_proc_rows.append(["Claim path — why it degraded", _opt(cp.degraded_reason)])
+        elif cp.head_forms:
+            claim_proc_rows.append(
+                [
+                    "Claim path — stored head forms",
+                    ", ".join(f"{k}: {v}" for k, v in sorted(cp.head_forms.items())),
+                ]
+            )
     store_tbl = rows_table(
         ["Field", "Value"],
         [
@@ -415,6 +439,7 @@ def status(
             ["Messages", db.messages],
             ["Events", db.events],
             ["Audit rows", db.audit],
+            *claim_proc_rows,
         ],
         adjustable=False,
     )

tests/golden/webconsole_seam.snapshot

@@ -5,7 +5,7 @@
 # This is a GOLDEN gate: any diff means the seam contract changed - see the test's failure hint.
 
 ## ENGINE_UI_SEAM
-15
+16
 
 ## dataclass messagefoundry.api._ui_seam.UiDeps
 engine_seam
@@ -170,7 +170,7 @@ SecurityPosture: allow_unencrypted_phi, backend, client_address_monoculture, cli
 ServiceStatusInfo: enabled, service_name, state
 StatsResetRequest: all, targets
 StatsResetTarget: channel_id, destination, role
-SystemStatus: db, engine, kpis, logs, pool, update
+SystemStatus: claim_proc, db, engine, kpis, logs, pool, update
 
 ## api.auth_models DTO fields rendered by the console
 AdGroupMap: entries