standard_health 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c32e1366e2b116f86a8be7780d4717a35b07952402f14e213a2533530c30fe8
-  data.tar.gz: 7c0fe9a0993be6e1ef46adcd95f3ba6c05dc029e7f621557ea314eb0a7062f0e
+  metadata.gz: 162374f071e6634d43876ef75f8fa6f50b1ec7bfd6a8d01bd94a91c854151d09
+  data.tar.gz: 58c40844359768a3d905c75575599dc1bf61dab15ebabc372c3e5e56cd4e169d
 SHA512:
-  metadata.gz: ad3e4a667c77a923dfa0ab49aa1de21f86923e7a1e30e7f7204c9ebb4c471f284f61c4f1d0a768155345da3fd46f10b7b77216d6feeeb0c9b799bc7f29bc02f7
-  data.tar.gz: '00853d5d4423f12269bf47f67692bcea3c43bc7da5ac9b64ff39fb9f080364131bea90156cc3fd41387d37421cef886695965c66d28fa024c9e3de418b07458b'
+  metadata.gz: a93890d618342991d02699f9a68d0cf432596f4fba5eff7659d4d4c8675d22e5e0bac3d996abed41e02ddd7f53b84c771f21e093a6c6e22b39404ec9ccc7498c
+  data.tar.gz: 13b347704251b47c6a877ce5fb559686d9fee639610109300da1fd989627010a3823f678ab420330a26ac851548647da3ab12405081cd13a2d9024c90d4bb5dc

data/CHANGELOG.md

@@ -7,6 +7,107 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-09-25
+
+### Fixed
+
+- **Skipped checks no longer degrade the aggregate.** A check that returns
+  `status: :skipped` itself means "not applicable here" (the feature it
+  covers is not configured or not enforced). It is now **neutral** in the
+  roll-up on every tier (`/ready` and the aggregate `/health`): it neither
+  degrades nor fails the status. Before, it counted like a failing
+  non-critical check, which held sidekick-web's `/health` at `degraded`
+  permanently while attestation was unconfigured. The row still renders in
+  `checks[]` with `"status": "skipped"`, and `check.completed` still fires,
+  so it stays visible. It is no longer listed in the `failed[]` / `failures`
+  of `ready.evaluated` / `aggregate.evaluated`, so the Logger and Sentry
+  notifiers don't name it as failing when something else degrades.
+- **A critical check that reports `:skipped` is neutral too**, on purpose.
+  "Not applicable" says nothing about whether the instance can serve, so it
+  must not pull it out of rotation. Return `:fail` for a state that should
+  page.
+- Real failures roll up exactly as before: a failing critical check is
+  `unavailable` (503), a failing non-critical one `degraded`, including
+  alongside a skipped check.
+- **Budget skips are unchanged.** A check the `total_check_budget` never
+  reached was not performed, which is not the same as healthy. It still
+  floors the roll-up at `degraded` (never `unavailable`) and is still listed
+  in `failed[]`. Its row now carries `budget_exhausted: true`, which is how
+  the gem tells the two kinds of skip apart.
+- `/diagnostics/env` is unaffected. Its roll-up is over env-audit rows and
+  assertions (`:ok` / `:warn` / `:error`), which have no skipped state.
+
+### Changed
+
+- **Requires Rails 8.1** (`rails >= 8.1`, was `>= 8.0`). Every consumer app
+  runs 8.1; 8.0 was never exercised in CI. Ruby 3.4 remains supported.
+
+### Upgrade notes (0.7.0 → 0.7.1)
+
+- **No required host change.** An app whose aggregate was `degraded` only
+  because of a self-reported skip now reports `ok`. Monitors or smoke tests
+  that expect `degraded` in that state need updating (sidekick-web).
+
+## [0.7.0] - 2026-09-24
+
+The Phase 4 release. 0.6 deprecated nothing, so nothing is removed. It adds
+the one extension point the app adoptions still needed their own controller
+for. The response of `/diagnostics/env` gains a key, and a failing assertion
+changes its `status`, so this ships as a minor.
+
+### Added
+
+- **`Configuration#register_diagnostics_assertion(name, callable = nil, &block)`**
+  adds a runtime assertion to the doctor tier. `/diagnostics/env` now renders
+  `assertions: [...]` next to `audit`. The key is always present (`[]` when
+  none are registered). Each callable returns a Hash with `status:` (`:ok` /
+  `:warn` / `:error`) plus detail keys, and the gem sets `name:`. A raise
+  becomes an `:error` row with `error_class` / `error` and is reported to
+  `Rails.error` as handled (`context: { diagnostics_assertion: name }`,
+  `source: "standard_health"`). A non-Hash result or an unknown status also
+  becomes an `:error` row. Re-registering a name replaces it (reload-safe).
+  `diagnostics_assertions` / `reset_diagnostics_assertions!` are provided.
+  Assertions never run on `/alive`, `/ready` or the aggregate tier, and stay
+  behind `diagnostics_basic_auth`.
+- **`StandardHealth::DiagnosticsAssertions.run` / `.failing?`**, public for
+  hosts that render their own diagnostics endpoint.
+
+### Changed
+
+- **`/diagnostics/env` `status` also rolls up assertions.** An `:error`
+  assertion makes it `incomplete` (`:warn` does not). The HTTP status is still
+  200. Nothing changes unless you register an assertion.
+- **`StandardHealth::DiagnosticsAuthentication` is public, semver-stable
+  API.** Including it into a host controller (as sidekick-web does) is now a
+  supported extension point: the include, its single `before_action`, and the
+  401 challenge / 403 fail-closed refusal. Its private method names are not
+  part of the contract.
+
+### Upgrade notes (0.6.x → 0.7.0)
+
+Grepped `origin/main` of sidekick-web, jumpdrive-web, fundbright-web,
+luminality-web and nutripod-web on 2026-09-24.
+
+- **No required host change.** Nothing was removed.
+- **Monitors or scripts that parse `/diagnostics/env`:** a new `assertions`
+  key appears, and `status` can become `incomplete` from an `:error`
+  assertion once you register one.
+- **sidekick-web (optional, recommended):** move the three assertions in
+  `app/controllers/health_diagnostics_controller.rb` (`statement_timeout`,
+  `rate_limit_store`, `attestation_roots`) into
+  `register_diagnostics_assertion` calls in
+  `config/initializers/standard_health.rb`. Then delete the controller and its
+  `config/routes.rb` route that shadows the engine's `/health/diagnostics/env`.
+  Keep each assertion's Hash shape. Drop the per-assertion
+  `rescue => e; { status: :error, error: e.message }`, which the gem now
+  provides (it also adds `error_class`). The response gains `status`, which
+  the host controller never rendered.
+- Other apps have no diagnostics controller of their own. Nothing to do.
+
+### Documentation
+
+- Aggregate-tier check **timeouts** are deliberately not sent to `Rails.error` (true since 0.6.1). A timeout is the gem's own budget firing on a slow dependency, already emitted as `standard_health.check.timed_out`, and the pre-0.6 host controllers had no per-check timeouts. A code comment and a spec now pin this.
+
 ## [0.6.1] - 2026-09-24
 
 ### Fixed

data/README.md

@@ -106,7 +106,7 @@ end
 | Status | HTTP | When |
 |---|---|---|
 | `unavailable` | 503 | a critical check failed, or a `:critical` circuit is red |
-| `degraded` | 200 | a non-critical check failed or was skipped, or the circuit roll-up is `:degraded` |
+| `degraded` | 200 | a non-critical check failed, a check was skipped by the total budget, or the circuit roll-up is `:degraded` |
 | `ok` | 200 | otherwise |
 
 **The aggregate tier re-runs your readiness checks by default.** With
@@ -130,7 +130,8 @@ A check that **raises** on this tier, rather than returning a `:fail` row, is
 also reported to `Rails.error` as handled (since 0.6.1), with context
 `{ health_check:, tier: "aggregate" }` and severity `:error` for a critical
 check or `:warning` otherwise. That matches what the pre-0.6 host controllers
-did. `/ready` does not do this: its failures reach Sentry through the
+did. Per-check timeouts are not reported; they surface as
+`standard_health.check.timed_out`. `/ready` does not do this: its failures reach Sentry through the
 transition-gated `ready.evaluated` notifier.
 
 With `aggregate_endpoint` off (the default) the engine's root route carries a
@@ -418,11 +419,13 @@ Since 0.4.1 the response carries a `status` alongside the audit, so a caller
 can gate on one field instead of re-implementing the roll-up:
 
 ```json
-{ "mode": "production", "status": "incomplete", "audit": [ ... ] }
+{ "mode": "production", "status": "incomplete", "audit": [ ... ], "assertions": [ ... ] }
 ```
 
 `incomplete` means at least one row is a **violation** — `missing`,
-`forbidden`, or `mismatch`. `should_set` is advisory and never affects it.
+`forbidden`, or `mismatch` — or (since 0.7.0) a registered diagnostics
+assertion reported `error`. `should_set` and an assertion's `warn` are
+advisory and never affect it.
 
 The level is deliberately not consulted for `mismatch`: a `recommended` var
 declared with an `expected_value:` that does not hold is a failed assertion,
@@ -433,6 +436,56 @@ not advice.
 free — which is why they joined this roll-up rather than getting a verdict of
 their own.
 
+### Runtime assertions: `register_diagnostics_assertion` (0.7.0)
+
+Env presence can't prove that a setting took effect. For example, the live
+`statement_timeout` may still be `0`, a rate limiter may have fallen back to
+Solid Cache, or a pinned certificate may be about to expire. Register those
+checks as assertions and the engine renders them on `/diagnostics/env` under
+`assertions:`, behind the same `diagnostics_basic_auth` gate:
+
+```ruby
+StandardHealth.configure do |c|
+  c.register_diagnostics_assertion(:statement_timeout) do
+    value = ActiveRecord::Base.connection.select_value("SHOW statement_timeout").to_s
+    { status: value.strip == "0" ? :warn : :ok, value: value, expected: "non-zero" }
+  end
+
+  # Any callable works; reference app constants inside it, not at boot.
+  c.register_diagnostics_assertion(:rate_limit_store, -> { RateLimitAssertion.call })
+end
+```
+
+```json
+{ "mode": "production", "status": "ok", "audit": [ ... ],
+  "assertions": [ { "name": "statement_timeout", "status": "ok", "value": "15s", "expected": "non-zero" } ] }
+```
+
+- The callable takes no arguments and returns a Hash with `status:` set to
+  `:ok`, `:warn` or `:error`. Other keys are rendered as-is. The gem sets
+  `name:`, and the callable can't override it.
+- An assertion that raises becomes `{ status: "error", error_class:, error: }`
+  and is reported to `Rails.error` as handled. The tier is authenticated, so
+  the message is shown. A non-Hash result or an unknown status also becomes an
+  `:error` row. One broken assertion never takes the endpoint down.
+- An `:error` row makes the top-level `status` `incomplete`. `:warn` does not.
+  The endpoint still returns 200.
+- Assertions run per request, and only on this tier, never on `/alive`,
+  `/ready` or the aggregate. They have no timeout, so keep them cheap.
+- Re-registering a name replaces it, so it is safe inside `to_prepare`.
+  `reset_diagnostics_assertions!` clears them in specs.
+- A host that keeps its own diagnostics controller can render
+  `StandardHealth::DiagnosticsAssertions.run` itself.
+
+**Replace your host code with it.** sidekick-web's
+`app/controllers/health_diagnostics_controller.rb` exists to add three
+assertions (`statement_timeout`, `rate_limit_store`, `attestation_roots`) to
+the env audit. Move each into a `register_diagnostics_assertion`, delete the
+controller, and delete its route
+(`get "/health/diagnostics/env", to: "health_diagnostics#env"` ahead of the
+engine mount). Its `rescue => e; { status: :error, error: e.message }`
+wrappers go too, because the gem does that now.
+
 ### Surfacing the audit on a health tier
 
 `/diagnostics/env` is authed and polled by nobody, so config drift declared in
@@ -608,11 +661,15 @@ c.diagnostics_basic_auth = {
   both, the parent's callbacks run first).
 - The request-time gate is the `StandardHealth::DiagnosticsAuthentication`
   concern, which the engine includes into its own `DiagnosticsController`.
-  sidekick-web also includes it into its own `HealthDiagnosticsController`
-  (an `ActionController::API` subclass) so that controller shares the same
-  gate. That works: the concern is a no-op until `diagnostics_basic_auth` is
-  set, and it adds one `before_action`. It is not yet a documented,
-  semver-stable extension point, so pin your minor version if you depend on it.
+  **Since 0.7.0 it is public, semver-stable API:** `include
+  StandardHealth::DiagnosticsAuthentication` into any `ActionController::API`
+  or `::Base` controller to put a host endpoint behind the same fail-closed
+  gate. The contract is the include, the one `before_action` it installs, and
+  the 401 challenge / 403 refusal behaviour. Its private method names are not
+  part of it. It is a no-op until `diagnostics_basic_auth` is set. If your
+  controller only exists to add runtime assertions, use
+  [`register_diagnostics_assertion`](#runtime-assertions-register_diagnostics_assertion-070)
+  instead and delete the controller.
 
 **Replace your host code with it.** Delete
 `app/controllers/standard_health_host_controller.rb` and the
@@ -749,9 +806,25 @@ go in `extra:`.
 
 The orchestrator should pull the instance out of rotation only on 503; degraded means "still serving, page someone."
 
-`skipped` also exists, for a check the total budget never reached (see
-Timeouts). A skip floors the roll-up at `degraded` and **never** produces
-`unavailable`, even for a critical check.
+`skipped` also exists, in two flavours that roll up differently:
+
+- **A check that returns `status: :skipped` itself** — "not applicable here"
+  (the feature it covers isn't configured or enforced). This is **neutral**
+  (since 0.7.1): it neither degrades nor fails the roll-up, whether the check
+  is critical or not, and it is left out of the evaluation events' `failed[]`.
+  It still renders in `checks[]` with `"status": "skipped"` and still emits
+  `check.completed`, so it stays visible. A critical check is neutral too on
+  purpose: "not applicable" says nothing about whether the instance can serve,
+  so it must not pull it out of rotation — and it must not mark it healthy
+  *because of* that check either; it simply doesn't count. If the state should
+  page, return `:fail`.
+- **A check the total budget never reached** (see Timeouts) — rendered with
+  `"budget_exhausted": true`. That check was not performed, which is not the
+  same as healthy, so it floors the roll-up at `degraded` and **never**
+  produces `unavailable`, even for a critical check.
+
+A real failure still rolls up exactly as before alongside any skip: a failing
+critical check is `unavailable`, a failing non-critical one `degraded`.
 
 ## Failure detail is redacted
 
@@ -877,8 +950,8 @@ slow-but-fine starts reporting `:fail`, and for a critical check that pulls
 the instance out of rotation. Pick values from observed `latency_ms` rather
 than intuition; that is what the `check.completed` events are for.
 
-Checks the total budget never reaches report `:skipped`, never silently `:ok`.
-A skip alone floors the roll-up at `degraded` — otherwise a slow *non-critical*
+Checks the total budget never reaches report `:skipped` (with
+`budget_exhausted: true`), never silently `:ok`. A budget skip alone floors the roll-up at `degraded` — otherwise a slow *non-critical*
 check could exhaust the budget, leave the database check unrun, and pull a
 healthy instance out of rotation.
 

data/app/controllers/concerns/standard_health/diagnostics_authentication.rb

@@ -7,6 +7,15 @@ module StandardHealth
   # `DiagnosticsController` only — never `HealthController` — so /alive and
   # /ready stay anonymous for orchestrator probes.
   #
+  # PUBLIC API (since 0.7.0, semver-stable): a host that serves its own
+  # diagnostics endpoint can `include StandardHealth::DiagnosticsAuthentication`
+  # into any ActionController::API or ::Base controller to put it behind the
+  # same fail-closed gate. The contract is the include, the `before_action`
+  # it installs, and the 401 challenge / 403 refusal behaviour below; the
+  # private method names are not part of it. Prefer
+  # `register_diagnostics_assertion` when all the host controller adds is
+  # assertions.
+  #
   # A NO-OP when `diagnostics_basic_auth` is unset, so hosts that gate
   # diagnostics through `diagnostics_parent_controller` see no change. Both
   # can be used together; the parent's callbacks run first.

data/app/controllers/standard_health/diagnostics_controller.rb

@@ -27,11 +27,13 @@ module StandardHealth
       root = defined?(Rails) ? Rails.root : nil
 
       audit = spec ? spec.audit(ENV.to_h, mode: mode, root: root) : []
+      assertions = DiagnosticsAssertions.run
 
       render json: {
         mode: mode,
-        status: audit_status(audit),
+        status: audit_status(audit, assertions),
         audit: audit,
+        assertions: assertions,
         generated_at: Time.now.utc.iso8601
       }
     end
@@ -53,13 +55,16 @@ module StandardHealth
     # advice. The advisory status stays `:should_set`, which is not a
     # violation.
     #
+    # A registered diagnostics assertion (`register_diagnostics_assertion`)
+    # that reports `:error` also makes it `:incomplete`; `:warn` does not.
+    #
     # The endpoint still returns 200 either way, so nothing that asserts on
     # the status code breaks.
-    def audit_status(audit)
+    def audit_status(audit, assertions = [])
       violated = Array(audit).any? do |row|
         EnvSpec::VIOLATION_STATUSES.include?(row[:status])
       end
-      violated ? :incomplete : :ok
+      (violated || DiagnosticsAssertions.failing?(assertions)) ? :incomplete : :ok
     end
   end
 end

data/lib/standard_health/aggregate_report.rb

@@ -18,8 +18,10 @@ module StandardHealth
   #
   # Status roll-up, in the estate's readiness vocabulary:
   #   :unavailable (503) — a critical check failed, or a :critical circuit is RED
-  #   :degraded    (200) — a non-critical check failed / was skipped, or the
-  #                        circuit roll-up is :degraded
+  #   :degraded    (200) — a non-critical check failed, a check was skipped
+  #                        by the total budget, or the circuit roll-up is
+  #                        :degraded. A check that reports :skipped itself
+  #                        (not applicable) is neutral — see Aggregator.
   #   :ok          (200) — otherwise
   #
   # StandardCircuit's own word for its worst state is `:critical`; it is
@@ -92,7 +94,7 @@ module StandardHealth
     # notifier logs this one (so redacted messages still reach logs); Sentry
     # and Metrics ignore it.
     def emit_evaluation(report, rows, circuits, started)
-      failing = rows.reject { |r| r[:status] == :ok }
+      failing = Aggregator.failing_rows(rows)
       payload = {
         status: report[:status],
         duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,

data/lib/standard_health/aggregator.rb

@@ -14,11 +14,23 @@ module StandardHealth
   # Runs all registered checks and rolls them up into a single status.
   #
   # Status semantics:
-  #   :ok           — every check returned :ok
+  #   :ok           — every check returned :ok, or reported :skipped itself
   #   :degraded     — at least one non-critical check failed, OR a check was
   #                   skipped because the total budget ran out
   #   :unavailable  — at least one critical check failed
   #
+  # Two kinds of :skipped row exist, and they roll up differently (0.7.1):
+  #
+  #   * A check that RETURNS `status: :skipped` is saying "not applicable
+  #     here" (the feature it covers is not configured or not enforced). That
+  #     is NEUTRAL — it neither degrades nor fails the tier, whatever its
+  #     `critical:` flag, and it is not listed in an evaluation event's
+  #     `failed[]`. The row still renders with status "skipped", and
+  #     `check.completed` still fires, so it stays visible.
+  #   * A check the total budget never REACHED (`budget_exhausted: true` on
+  #     the row) was not performed at all, and an unperformed check is not a
+  #     healthy one. It floors the tier at :degraded — never :unavailable.
+  #
   # The aggregator never raises. Each check is invoked through `safe_run`
   # which catches `StandardError` so a buggy custom check cannot take down
   # /ready. Instrumentation is held to the same bar — every emit is wrapped
@@ -55,7 +67,7 @@ module StandardHealth
       duration_ms = ((monotonic - started) * 1000).round
       status = overall_status(check_rows)
 
-      failing = check_rows.reject { |r| r[:status] == :ok }
+      failing = failing_rows(check_rows)
 
       return { status: status, checks: check_rows, generated_at: now.iso8601 } unless tier == :ready
 
@@ -81,6 +93,21 @@ module StandardHealth
       }
     end
 
+    # The rows an evaluation event reports as failing: everything that is not
+    # :ok, except a check that reported :skipped itself (not applicable, so
+    # not a failure). A budget skip IS listed — it is the only place a skip
+    # shows up in the transition-gated event. @api private (also used by
+    # AggregateReport).
+    def self.failing_rows(rows)
+      rows.reject { |r| r[:status] == :ok || neutral_skip?(r) }
+    end
+
+    # A row the check itself reported as :skipped — "not applicable here".
+    # Neutral in the roll-up. A budget skip is not neutral. @api private
+    def self.neutral_skip?(row)
+      row[:status] == :skipped && !row[:budget_exhausted]
+    end
+
     # Per-failure detail for an evaluation event. Public (but @api private) so
     # the aggregate tier's evaluation event carries the same shape.
     # @api private
@@ -111,6 +138,12 @@ module StandardHealth
       emit_check(row, tier)
       row
     rescue CheckTimeout
+      # Deliberately NOT sent to Rails.error (unlike the StandardError branch
+      # below). A timeout is our own budget firing on a slow dependency, not a
+      # bug in the check: it is already visible as `check.timed_out` and as a
+      # failing row, and reporting it per poll would page on latency. The
+      # pre-0.6 host aggregate controllers had no per-check timeouts, so
+      # nothing reported there is lost.
       emit("standard_health.check.timed_out",
            name: reg.name, critical: reg.critical, timeout_s: timeout, **tier_attrs(tier))
       row = {
@@ -171,12 +204,15 @@ module StandardHealth
     private_class_method :budget_exhausted?
 
     # A check the total budget never reached. `:skipped`, never silently
-    # `:ok` — an unperformed check is not a healthy one.
+    # `:ok` — an unperformed check is not a healthy one. `budget_exhausted`
+    # is what separates it from a check that reported :skipped itself (which
+    # is neutral); see overall_status.
     def self.skipped_row(reg, budget)
       {
         name: reg.name,
         critical: reg.critical,
         status: :skipped,
+        budget_exhausted: true,
         error: "skipped — total check budget of #{budget}s exhausted"
       }
     end
@@ -185,10 +221,16 @@ module StandardHealth
     def self.overall_status(rows)
       return :ok if rows.empty?
 
-      failures = rows.reject { |r| r[:status] == :ok }
+      # A check that reported :skipped itself is not applicable here, so it is
+      # NEUTRAL: it must not degrade the tier (sidekick-web's non-critical
+      # attestation check held /health at "degraded" forever while attestation
+      # was simply not configured), and a critical one must not fail it
+      # either — "not applicable" says nothing about whether the app can
+      # serve. It stays in checks[] as "skipped" for visibility.
+      failures = failing_rows(rows)
       return :ok if failures.empty?
 
-      # A SKIP MUST NEVER PRODUCE :unavailable, even for a critical check.
+      # A BUDGET SKIP MUST NEVER PRODUCE :unavailable, even for a critical check.
       # Otherwise a slow *non-critical* check could exhaust the budget, leave
       # the database check unrun, and pull a perfectly healthy instance out of
       # rotation — a self-inflicted outage caused by the safety mechanism.

data/lib/standard_health/check.rb

@@ -11,6 +11,16 @@ module StandardHealth
   #
   #   { status: :fail, error: "connection refused" }
   #
+  # or, when the check does not apply to this deployment (the feature it
+  # covers is not configured or not enforced):
+  #
+  #   { status: :skipped }
+  #
+  # A self-reported :skipped is NEUTRAL in the roll-up (0.7.1): it never
+  # degrades or fails the tier, even for a critical check, but it still
+  # renders in `checks[]` as "skipped". Return :fail, not :skipped, for
+  # anything that should page.
+  #
   # The `with_timing` helper wraps a block, captures latency, and converts
   # any unhandled `StandardError` into a `:fail` row so subclasses don't
   # have to repeat the pattern.

data/lib/standard_health/configuration.rb

@@ -192,7 +192,9 @@ module StandardHealth
     attr_accessor :default_check_timeout
 
     # Budget across all checks, evaluated BEFORE each check starts. Checks not
-    # reached are reported :skipped, and a skip alone floors the roll-up at
+    # reached are reported :skipped with `budget_exhausted: true` (unlike a
+    # check that reports :skipped itself, which is neutral), and such a skip
+    # alone floors the roll-up at
     # :degraded — never :unavailable. Otherwise a slow NON-critical check could
     # exhaust the budget, leave a critical check unrun, and pull a healthy app
     # out of rotation. nil = no budget.
@@ -220,6 +222,7 @@ module StandardHealth
       @env_spec = nil
       @checks = []
       @aggregate_checks = []
+      @diagnostics_assertions = []
       @aggregate_endpoint = false
       @aggregate_readiness_checks = true
       @aggregate_circuits = true
@@ -368,6 +371,51 @@ module StandardHealth
       registration
     end
 
+    DiagnosticsAssertion = Struct.new(:name, :callable)
+
+    # Adds a runtime assertion to the doctor tier (`GET /diagnostics/env`),
+    # rendered under `assertions:` next to the env audit. For facts env
+    # presence can't prove: the live `statement_timeout`, the cache store a
+    # rate limiter actually resolved to, a pinned root's expiry. Replaces a
+    # host diagnostics controller that exists only to add these.
+    #
+    #   c.register_diagnostics_assertion(:statement_timeout) do
+    #     value = ActiveRecord::Base.connection.select_value("SHOW statement_timeout").to_s
+    #     { status: value == "0" ? :warn : :ok, value: value, expected: "non-zero" }
+    #   end
+    #
+    # The callable takes no arguments and returns a Hash with `status:`
+    # (`:ok`, `:warn` or `:error`) plus any detail keys. `name:` is set by
+    # the gem. It runs per request, on the authenticated tier only, never on
+    # /alive, /ready or the aggregate. A raise, a non-Hash, or an unknown
+    # status becomes an `:error` row (a raise is also reported to
+    # `Rails.error` as handled). An `:error` row makes the endpoint's
+    # `status` `incomplete`; `:warn` does not.
+    #
+    # Re-registering a name replaces it, so `configure` can safely re-run
+    # from `to_prepare` on reload.
+    def register_diagnostics_assertion(name, callable = nil, &block)
+      callable ||= block
+      unless callable.respond_to?(:call)
+        raise ArgumentError, "register_diagnostics_assertion(#{name.inspect}) needs a callable or a block"
+      end
+
+      assertion = DiagnosticsAssertion.new(name.to_sym, callable)
+      @diagnostics_assertions.reject! { |existing| existing.name == assertion.name }
+      @diagnostics_assertions << assertion
+      assertion
+    end
+
+    # @return [Array<DiagnosticsAssertion>] in registration order
+    def diagnostics_assertions
+      @diagnostics_assertions.dup
+    end
+
+    # Drop registered diagnostics assertions. Test hygiene.
+    def reset_diagnostics_assertions!
+      @diagnostics_assertions = []
+    end
+
     # @return [Array<Registration>] aggregate-only checks
     def aggregate_checks
       @aggregate_checks.dup

data/lib/standard_health/diagnostics_assertions.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module StandardHealth
+  # Runs the host's `register_diagnostics_assertion` callables for the doctor
+  # tier (`/diagnostics/env`, behind `diagnostics_basic_auth`).
+  #
+  # An assertion is a runtime fact that env presence cannot express: the live
+  # `statement_timeout`, which cache store a limiter actually resolved to, how
+  # close a pinned certificate is to expiry. Each callable returns a Hash with
+  # at least `status:` (`:ok`, `:warn` or `:error`); any other keys (`value:`,
+  # `expected:`, ...) are rendered as-is. The gem sets `name:`.
+  #
+  # Public: a host with its own diagnostics controller can render
+  # `StandardHealth::DiagnosticsAssertions.run` itself.
+  module DiagnosticsAssertions
+    STATUSES = %i[ok warn error].freeze
+
+    module_function
+
+    # @return [Array<Hash>] one row per registered assertion, in registration
+    #   order. Never raises: an assertion that raises, returns a non-Hash, or
+    #   returns an unknown status becomes an `:error` row.
+    def run(config = StandardHealth.config)
+      config.diagnostics_assertions.map { |assertion| evaluate(assertion) }
+    end
+
+    # True when any row is `:error`. `:warn` is advisory.
+    def failing?(rows)
+      Array(rows).any? { |row| row[:status] == :error }
+    end
+
+    def evaluate(assertion)
+      result = assertion.callable.call
+      return invalid(assertion.name, "returned #{result.class}, expected a Hash") unless result.is_a?(Hash)
+
+      row = result.to_h.transform_keys(&:to_sym)
+      status = row[:status].respond_to?(:to_sym) ? row[:status].to_sym : nil
+      return invalid(assertion.name, "returned status #{row[:status].inspect}, expected one of #{STATUSES.inspect}") unless STATUSES.include?(status)
+
+      { name: assertion.name }.merge(row.except(:name)).merge(status: status)
+    rescue StandardError => e
+      report(e, assertion.name)
+      # The doctor tier is authenticated, so the message is shown (the /ready
+      # redaction rationale does not apply); the class is kept separately
+      # for grouping.
+      { name: assertion.name, status: :error, error_class: e.class.name, error: e.message }
+    end
+
+    def invalid(name, detail)
+      { name: name, status: :error, error: "diagnostics assertion #{name} #{detail}" }
+    end
+
+    def report(error, name)
+      return unless defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
+
+      ::Rails.error.report(error, handled: true, severity: :warning,
+        context: { diagnostics_assertion: name }, source: "standard_health")
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/standard_health/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StandardHealth
-  VERSION = "0.6.1"
+  VERSION = "0.7.1"
 end

data/lib/standard_health.rb

@@ -22,6 +22,7 @@ require "standard_health/subscribers"
 require "standard_health/redactor"
 require "standard_health/aggregator"
 require "standard_health/aggregate_report"
+require "standard_health/diagnostics_assertions"
 
 module StandardHealth
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_health
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.1
 platform: ruby
 authors:
 - Jaryl Sim
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '8.0'
+        version: '8.1'
 description: StandardHealth is a mountable Rails engine providing /alive, /ready,
   and /diagnostics/env endpoints, with a configuration block for registering custom
   checks and a DSL for declaring required and recommended environment variables.
@@ -54,6 +54,7 @@ files:
 - lib/standard_health/checks/solid_cache.rb
 - lib/standard_health/checks/solid_queue.rb
 - lib/standard_health/configuration.rb
+- lib/standard_health/diagnostics_assertions.rb
 - lib/standard_health/diagnostics_basic_auth.rb
 - lib/standard_health/engine.rb
 - lib/standard_health/env_spec.rb
@@ -87,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A drop-in health check and environment-spec engine for Rails 8 host apps.
 test_files: []