standard_health 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73c1743f46e03601e44970d282ca02dd195b22e5f22fe502e20e8a45281e0d69
-  data.tar.gz: 507f8e5fda5420690b7146b0f6a9136561c0a1b61d6c567c5be3dcd5c250be61
+  metadata.gz: 3d6a6ea3266864aaa15232529241e2040a836d810c4898eb512746e78a582901
+  data.tar.gz: fc9575f2c3e425a6065e3e5285094d03ba5cd694848c386937251b0fea5d75af
 SHA512:
-  metadata.gz: 38b527cf8973dc2557b1b8c13e40ace60f73efb78f1aab34100b4a51cf4f53069700c7ac0047f038a9bcf5fdcb9a1f3223fa92ddc653e1293f6c5d4b51f320ed
-  data.tar.gz: 3662477381f1149d26394ba63fc2380c2104d1cb78a65bf3d943681a907b591ad0e7e9a6f990c868cf48087306cf6cb845c399fd976a346858ba083647b6bc3e
+  metadata.gz: 83a04f1025e9e8b6e62344ff53828a716c262d7779d30f64afeb69b704fb34289e9138f751a93fb46215ba24c71612e17e9cfd7a37c859ac67feca64bbb2e25a
+  data.tar.gz: 6cf0b8d3a4100e8d3737eb1bbaddfb7c1a40d6dd77ad4e9c097ad547308ff196fb012b46ebb7c1d267b30d784abc863f734df4bd8520971d99af9d705e2af51b

data/CHANGELOG.md

@@ -7,6 +7,186 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-30
+
+Closes the gap that had four host apps writing their own checks. The env-spec
+DSL could only audit **presence**, so "this toggle must not be set on
+production" and "this value must be exactly `false`" were inexpressible — and
+the workaround was a hand-written check carrying a duplicate list of variable
+names, kept in sync with the spec by comment.
+
+Everything here is **additive and opt-in**. No check is auto-registered and no
+existing status changes meaning, so this is a pure `bundle update` for
+consumers on `~> 0.4`.
+
+### Added
+
+- **`forbidden` EnvSpec level.** Inverts the presence rule: absent is `:ok`,
+  present reports the new `:forbidden` status. For dangerous ops toggles —
+  demo modes, auth bypasses, bootstrap flags — that are legitimate on staging
+  and must never survive promotion. Composes with `in:`, `mode_alias`, groups
+  and the `if:`/`unless:` predicates like any other level.
+- **`expected_value:` assertion** on `required` / `recommended`. Asserts the
+  value, not just presence; a present-but-wrong value reports the new
+  `:mismatch` status. Accepts a String, an Array (any-of), a Regexp (matched,
+  not compared), or any object comparable by its string form. The **actual
+  value is never surfaced** — env values are routinely secrets — only the
+  declared expectation.
+- **`Checks::EnvSpecAudit`** (opt-in). Runs the configured `env_spec` and
+  fails on `:missing` / `:forbidden` / `:mismatch`, reporting offending
+  variable *names* grouped by status. Reads the spec directly, so there is no
+  second list to drift. Non-critical by default: config drift is visibility,
+  not a rotation signal. Skips `consumed_by` resolution — that is file IO per
+  entry, fine for an on-demand doctor endpoint and not on a polled tier.
+- **`Checks::SolidCable`** (opt-in). Bounded read against
+  `solid_cable_messages`. Promoted from sidekick-web. Falls back to the
+  primary connection when SolidCable isn't pointed at its own database.
+- **`standard_health:install` generator.** Writes the initializer and mounts
+  the engine, with the aggregate-route ordering requirement noted inline.
+  Idempotent; `--skip-initializer`, `--skip-routes`, `--force`.
+
+### Changed
+
+- **`/diagnostics/env` top-level `status`** now reports `incomplete` for
+  `:forbidden` and `:mismatch` rows as well as `:missing`. Callers already
+  gating on that one field pick up the new assertions for free, which is why
+  they joined the existing roll-up instead of getting a verdict of their own.
+  The endpoint still returns 200 either way. `:should_set` remains advisory
+  and still never affects the roll-up.
+- **Rails dependency relaxed** from `~> 8.0` to `>= 8.0`, matching the rest of
+  the `standard_*` family. `~> 8.0` was the only floor in the family that
+  would have blocked a Rails 9 host.
+
+### Not in this release
+
+- **Timeout defaults remain unset.** 0.4.1 said sensible `default_check_timeout`
+  / budget values would be chosen "in 0.5.0". They are not: choosing them still
+  needs enough real p99 latency data from the instrumentation 0.4.1 added, and
+  guessing a timeout on a health check is how you cause the outage you were
+  trying to prevent. The machinery stays opt-in per check. The stale promise in
+  `Configuration` has been repointed (#48).
+- **`/diagnostics/env` still returns 200** when `status` is `incomplete`.
+  Turning that into a 503 is a breaking contract change for any caller gating on
+  the response code, so it wants its own decision rather than riding along with
+  an otherwise additive release.
+
+### Documentation
+
+- **The aggregate `GET /health` tier and its ordering requirement are now
+  documented.** The engine draws sub-paths only; the aggregate tier is the
+  host's job and must be drawn **before** `mount`. An app that mounts first
+  and relies on the engine to serve it silently has no aggregate tier — no
+  boot error, no failing route spec. Also documents what each of the four
+  tiers is for, and that readiness gates only on hard infra the app owns.
+- New README section on opt-in checks, including why nothing here
+  auto-registers.
+
+## [0.4.1] - 2026-07-29
+
+Observability release. Until now the gem emitted **nothing** — no events, no
+logs, no metrics. It computed `latency_ms` for every check and discarded it
+into the response body. A failing check was invisible unless somebody happened
+to call `/ready` at the right moment, so there was no history, no alerting
+hook, and no way to chart check latency.
+
+Everything here is **additive**: no status code, roll-up rule, or response
+field changes meaning, so this is a pure `bundle update` for consumers on
+`~> 0.4`.
+
+### Added
+
+- **Instrumentation.** Three events over whichever bus is live (`Rails.event`
+  on Rails 8.1+, `ActiveSupport::Notifications` otherwise), matching
+  `standard_circuit`'s `EventEmitter` idiom:
+  - `standard_health.check.completed` — `name`, `critical`, `status`,
+    `latency_ms`, `error_class`, `error_message`
+  - `standard_health.check.timed_out` — `name`, `critical`, `timeout_s`
+  - `standard_health.ready.evaluated` — `status`, `duration_ms`, `failed[]`
+- **Three built-in subscribers**, registered by a new engine initializer
+  (`after: :load_config_initializers`, so host config is final):
+  - `Notifiers::Logger` — **silent while healthy.** `warn` on degraded,
+    `error` on unavailable. Health events are polls (~6/min/instance), not
+    transitions; a line per evaluation is ~8,640/day/instance of "everything
+    is fine".
+  - `Notifiers::Sentry` — **transition-only**, with a 60s repeat floor and
+    one `info` on recovery. Capturing every non-ok poll would turn a
+    five-minute outage into ~30 duplicate issues. Mutex-guarded (Puma is
+    threaded). Sentry stays a soft dependency.
+  - `Notifiers::Metrics` — per-poll counters and latency distributions. This
+    fires on every evaluation on purpose: it is what makes `latency_ms`
+    chartable.
+- `config.add_notifier` for host-supplied `call(event_name, payload)`
+  subscribers, validated at add time.
+- Config: `instrumentation_enabled`, `logger`, `sentry_enabled`,
+  `metric_prefix`.
+- **Per-check timeout machinery** — `default_check_timeout`,
+  `total_check_budget`, and a `timeout:` option on `register_check`. Uses a
+  dedicated `StandardHealth::CheckTimeout` rather than bare `Timeout::Error`,
+  so a timeout the host raised for its own reasons is never mislabelled as
+  ours. **All default to `nil` (OFF)** — see below.
+- `status` on `/diagnostics/env`: `:ok` or `:incomplete` (a `required` var is
+  missing). **Additive — the endpoint still returns 200 either way.**
+
+### Fixed
+
+- `Check#with_timing` now records `error_class` alongside the message. All
+  three built-in checks route through it, so without this every real driver
+  failure reached the aggregator with no class and the redacted body fell back
+  to a generic `StandardError` — exactly the useless label redaction exists to
+  replace.
+- Failure detail (`error_class` + `error_message`) now rides on
+  `ready.evaluated`, not only on `check.completed`. Both built-in subscribers
+  are driven by `ready.evaluated` (deliberately — it is the transition-gated
+  event), so the message would otherwise have been deleted from the response
+  without ever reaching logs or Sentry.
+
+### Security
+
+- **`/ready` no longer returns raw exception messages.** The endpoint is
+  unauthenticated by design, and a driver error will happily tell an anonymous
+  caller the database host, port and username — during exactly the incident
+  you least want to be leaking. Failing rows now carry `error_class` and a
+  stable `error_code` instead. The full message is not lost: it goes to logs
+  and Sentry via the instrumentation above, which is why redaction ships in
+  the same release rather than separately.
+  - `config.expose_check_errors = true` restores the previous bodies.
+  - `config.detail_token` + an `X-Health-Token` header is a break-glass path
+    for on-call, compared in constant time.
+  - `status`, `name`, `critical`, `latency_ms` and `generated_at` are
+    unchanged, so dashboards and existing specs keep working.
+
+### Notes on what is deliberately NOT on
+
+Timeouts and the total budget default to **off**, giving byte-identical
+behaviour to 0.4.0. Turning them on is a semantic change: a check that has
+always been slow-but-fine starts reporting `:fail`, and for a critical check
+that pulls the instance out of rotation. Shipping that in a patch, to five
+apps, on a `bundle update`, is how you cause the outage you were preventing.
+
+The machinery ships now so apps can opt in per check, and so the events above
+can reveal the real p99 latencies. Defaults get chosen from that data in
+0.5.0, which requires an explicit Gemfile edit.
+
+One semantic guard is already in place for when they are enabled: a check
+skipped because the budget ran out reports `:skipped` and floors the roll-up
+at `:degraded` — **never `:unavailable`**, even when the skipped check is
+critical. Otherwise a slow *non-critical* check could exhaust the budget,
+leave the database check unrun, and pull a healthy instance out of rotation.
+
+`total_check_budget` bounds **how many checks run**, not how long the probe
+takes — it is evaluated before each check starts, not during one. Clamping
+each check to the remaining budget would close that gap but would apply
+`Timeout.timeout` to checks whose author never asked for one, so setting a
+budget deliberately does not opt you into that. Asserted by spec, not just
+documented.
+
+A second reason to leave them off: `Timeout.timeout` raises into the running
+thread at an arbitrary point, so firing one mid-connection-checkout can return
+a broken connection to the pool. The dedicated `CheckTimeout` fixes
+mislabelling, not this. The README now carries the full caveat — the right
+answer for datastore checks is usually a driver-level timeout
+(`connect_timeout` / `statement_timeout`), not this setting.
+
 ## [0.4.0] - 2026-05-05
 
 ### Added

data/{MIT-LICENSE → LICENSE}

@@ -1,4 +1,6 @@
-Copyright (c) 2026 Jaryl Sim
+The MIT License (MIT)
+
+Copyright (c) 2026 Rarebit One
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -13,8 +15,8 @@ included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -18,7 +18,16 @@ Add to your Gemfile:
 gem "standard_health"
 ```
 
-Then `bundle install`.
+Then `bundle install`, and run the install generator:
+
+```bash
+bin/rails generate standard_health:install
+```
+
+It writes `config/initializers/standard_health.rb` and mounts the engine in
+`config/routes.rb` with the ordering requirement below noted inline. It is
+idempotent — re-running skips what is already installed. Flags:
+`--skip-initializer`, `--skip-routes`, `--force` (overwrite the initializer).
 
 ## Mounting
 
@@ -34,9 +43,45 @@ This wires up:
 - `GET /health/ready`
 - `GET /health/diagnostics/env`
 
+### The aggregate `GET /health` is yours to draw — before the mount
+
+**The engine draws sub-paths only.** There is no `GET /health` in
+`config/routes.rb` here; the aggregate tier is the host's responsibility, and
+the ordering is not optional:
+
+```ruby
+get "/health", to: "health_aggregate#show"          # aggregate — FIRST
+mount StandardHealth::Engine => "/health", as: :standard_health
+```
+
+An app that mounts the engine **first** and relies on it to serve the aggregate
+tier **silently has no aggregate tier at all** — no boot error, no 404 at boot,
+and no failing route spec unless one exists. The failure surfaces as a
+dashboard that has been reading nothing for months. Add a route spec asserting
+`GET /health` resolves.
+
+Why this way round: `mount` claims the `/health` prefix, so a bare `GET /health`
+drawn *after* it still resolves (the engine has no route for the bare path) —
+but nothing about that is obvious from reading the file, and getting it
+backwards fails silently either way. Draw it first and the ordering question
+never arises.
+
+The four tiers, and what each is for:
+
+| Route | Tier | Consumer |
+|---|---|---|
+| `GET /health/alive` | liveness — process is up | restart probes, CI reachability gates |
+| `GET /health/ready` | readiness — **rotation gate** | load balancer / platform health check |
+| `GET /health` | aggregate — full picture | dashboards, humans |
+| `GET /health/diagnostics/env` | doctor (authed) | on-call, config audits |
+
+Readiness gates **only** on hard infra the app owns. A soft upstream that
+degrades must not pull an instance out of rotation — put those on the aggregate
+tier instead.
+
 ## Configuration
 
-Create `config/initializers/standard_health.rb`:
+Create `config/initializers/standard_health.rb` (or let the generator write it):
 
 ```ruby
 StandardHealth.configure do |c|
@@ -62,18 +107,21 @@ end
 
 ## EnvSpec
 
-The DSL has two declarations:
+The DSL has three declarations:
 
 - `required :NAME` — missing value reports `status: :missing`
 - `recommended :NAME` — missing value reports `status: :should_set`
+- `forbidden :NAME` — **present** value reports `status: :forbidden`; absent is `:ok`
 
-Both accept:
+All three accept:
 
 - `in: %w[staging production]` — restricts the entry to those `APP_ENVIRONMENT` values; ignored otherwise. May also be a Symbol resolved via `mode_alias` (see below).
 - `description: "..."` — surfaced verbatim in the audit JSON
 - `consumed_by: "config/initializers/sentry.rb"` — pointer (or `Array<String>`) to where the value is read; surfaced verbatim
 - `if: -> { ... }` / `unless: -> { ... }` — Proc predicates evaluated at audit time. When `unless:` returns truthy or `if:` returns falsy, the entry is reported with `status: :not_applicable`
 
+`required` and `recommended` additionally accept `expected_value:` (see below). `forbidden` does not — its assertion *is* "absent" — and combining them raises an `ArgumentError` at `define` time rather than silently ignoring the option.
+
 Audit output (one row per applicable entry):
 
 ```json
@@ -85,7 +133,68 @@ Audit output (one row per applicable entry):
 }
 ```
 
-Possible `status` values are `ok`, `missing` (required + absent), `should_set` (recommended + absent), and `not_applicable` (suppressed by an `if:`/`unless:` predicate).
+Possible `status` values:
+
+| status | meaning |
+|---|---|
+| `ok` | nothing to report |
+| `missing` | `required` + absent |
+| `should_set` | `recommended` + absent (advisory) |
+| `forbidden` | `forbidden` + **present** |
+| `mismatch` | present, but `expected_value:` says otherwise |
+| `not_applicable` | suppressed by an `if:`/`unless:` predicate |
+
+`missing`, `forbidden` and `mismatch` are the **violation** statuses — they drive the top-level `status: "incomplete"` and the optional `EnvSpecAudit` check. `should_set` is advisory and never counts as a violation.
+
+### `forbidden`: vars that must NOT be set
+
+For dangerous ops toggles — demo modes, auth bypasses, bootstrap flags — that are legitimate on staging and must never survive promotion to production:
+
+```ruby
+mode_alias :live, %w[production]
+
+group "Production-forbidden toggles" do
+  forbidden :DEMO_MODE_ENABLED, in: :live,
+    description: "Demo/ops dashboard surfaces; unset before promoting"
+  forbidden :STANDARD_ID_BYPASS_CODE, in: :live,
+    description: "Fixed E2E OTP bypass code; staging only"
+end
+```
+
+```json
+{ "name": "DEMO_MODE_ENABLED", "level": "forbidden", "status": "forbidden", "mode": "production" }
+```
+
+Before this level existed, hosts expressed "forbidden" by declaring the var `recommended` with an `if: -> { ENV[...].present? }` predicate so that a set toggle at least produced a row — but the row was a green `:ok`, so the signal had to be carried by a hand-written custom check with its own duplicate list of toggle names. `forbidden` replaces both halves.
+
+### `expected_value:`: assert the value, not just presence
+
+Presence auditing misses the case where a var is set to the *wrong* thing — which for a security toggle is the failure mode that matters:
+
+```ruby
+# CSP is only enforced when this is exactly the string "false";
+# "true" passes a presence audit while leaving the CSP report-only.
+required :CONTENT_SECURITY_POLICY_REPORT_ONLY, in: :live,
+  expected_value: "false",
+  description: "Any other value leaves the CSP report-only"
+
+required :LOG_LEVEL, expected_value: %w[info warn]   # any of
+required :DATABASE_URL, expected_value: /\Apostgres:/ # matched, not compared
+```
+
+A present-but-wrong value reports `status: :mismatch`. An absent value still reports `:missing` / `:should_set` — there is nothing to compare. Comparison is on the string form, so `expected_value: 3000` matches `"3000"`.
+
+**The actual value is never surfaced.** Env values are routinely secrets, and the endpoint exists to report *that* something is wrong, not to echo it back. The row carries the declared `expected_value` (host config, safe) and nothing else:
+
+```json
+{
+  "name": "CONTENT_SECURITY_POLICY_REPORT_ONLY",
+  "level": "required",
+  "status": "mismatch",
+  "expected_value": "false",
+  "mode": "production"
+}
+```
 
 ### Predicates: `if:` and `unless:`
 
@@ -184,6 +293,41 @@ Audit rows for entries declared inside a `group` block carry a `group` key:
 
 Entries declared outside any `group` block omit the `group` key entirely.
 
+### Top-level status
+
+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": [ ... ] }
+```
+
+`incomplete` means at least one row is a **violation** — `missing`,
+`forbidden`, or `mismatch`. `should_set` is advisory and never affects 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,
+not advice.
+
+**The endpoint still returns 200 either way.** Callers that already gate on
+`status == "incomplete"` pick up the `forbidden` and `mismatch` assertions for
+free — which is why they joined this roll-up rather than getting a verdict of
+their own.
+
+### Surfacing the audit on a health tier
+
+`/diagnostics/env` is authed and polled by nobody, so config drift declared in
+the spec is invisible until someone looks. Register the opt-in `EnvSpecAudit`
+check to put the same verdict on a health tier:
+
+```ruby
+c.register_check :env_spec, StandardHealth::Checks::EnvSpecAudit
+```
+
+It fails on `:missing` / `:forbidden` / `:mismatch` rows and reports the
+offending **names** (never values). Non-critical by default — see
+[Opt-in checks](#opt-in-checks).
+
 ### Backward compatibility
 
 All v0.2.0 specs continue to produce identical audit output in v0.3.0. The new fields (`description`, `consumed_by`, `group`, `reason`) appear only when the corresponding feature is used; the new `:not_applicable` status only appears when a predicate suppresses an entry.
@@ -206,6 +350,81 @@ end
 
 `with_timing` captures `latency_ms` on success and converts any `StandardError` into `{ status: :fail, error: <message> }`.
 
+**A check must never raise.** `Aggregator` rescues `StandardError` per check, so a buggy check degrades to `:fail` rather than 500ing the endpoint — but don't rely on that as the only line of defence. Route fallible work through `with_timing`.
+
+## Opt-in checks
+
+Every check in this gem must be registered explicitly; **none are registered
+automatically**, including the ones below. That is a deliberate constraint on
+the gem: auto-registering a check turns it on for every host on a `bundle
+update`, and a host that has never had SolidCable installed — or whose env spec
+has a pre-existing violation — would go from green to yellow across its estate
+for a check nobody asked for. New checks are additive only when they are opt-in.
+
+| Check | Probes | `critical:` default |
+|---|---|---|
+| `Checks::ActiveRecord` | `SELECT 1` on the primary connection | `true` |
+| `Checks::SolidQueue` | SolidQueue's tables | `true` |
+| `Checks::SolidCache` | read-only `Rails.cache` probe | `false` |
+| `Checks::SolidCable` | `solid_cable_messages` store | `false` |
+| `Checks::EnvSpecAudit` | the configured `env_spec` | `false` |
+
+The `critical:` default is only a default — `register_check` overrides it, and
+what belongs on the rotation gate is a per-app decision.
+
+```ruby
+StandardHealth.configure do |c|
+  c.register_check :solid_cable, StandardHealth::Checks::SolidCable
+  c.register_check :env_spec, StandardHealth::Checks::EnvSpecAudit
+end
+```
+
+### `Checks::SolidCable`
+
+Bounded read against `solid_cable_messages`, confirming both that the cable
+schema is migrated and that its connection is up. Uses
+`SolidCable::Record.connection` when SolidCable is pointed at a separate
+database, falling back to the primary connection when it isn't.
+
+Cable is a **degradable feature dependency** — prefer this on the aggregate
+tier. A broken cable store should mark the app `degraded`, never de-rotate it.
+
+### `Checks::EnvSpecAudit`
+
+Runs the configured `env_spec` and fails on the violation statuses
+(`:missing`, `:forbidden`, `:mismatch`), reporting the offending variable
+**names** grouped by status. Values never appear.
+
+It reads the spec directly, so there is one declaration and no second list to
+keep in sync — which is the whole reason it exists. It skips `consumed_by`
+resolution (that does file IO per entry, fine for an on-demand doctor endpoint
+and not fine on a tier polled every few seconds), and it is `:ok` when no
+`env_spec` is configured.
+
+Non-critical by default, and that default is load-bearing: config drift is
+*visibility*, not a rotation signal. An instance with a stale toggle set is
+still serving traffic correctly, and de-rotating it converts a warning into an
+outage. Registering it `critical: true` asserts "this app must not serve at all
+with a bad env" — a real but rare posture. Know which you want.
+
+The aggregator instantiates checks with `name:`/`critical:` only, so to narrow
+what counts as a failure, subclass:
+
+```ruby
+class ForbiddenTogglesOnly < StandardHealth::Checks::EnvSpecAudit
+  def initialize(name: :forbidden_toggles, critical: false)
+    super(name: name, critical: critical, fail_on: %i[forbidden])
+  end
+end
+```
+
+Note the failure message is subject to [redaction](#failure-detail-is-redacted)
+on `/ready` like any other check; the detail reaches you through logs and
+Sentry. The row carries a stable `error_class` of
+`StandardHealth::EnvSpecViolation`, so the redacted body still groups on
+`error_code: "standard_health_env_spec_violation"` rather than a useless
+`standard_error`.
+
 ## Auth
 
 `/alive` and `/ready` are typically left open for orchestrator probes. `/diagnostics/env` enumerates which env vars are missing — that's potentially sensitive, so the host app is responsible for protecting it.
@@ -283,6 +502,130 @@ When `diagnostics_parent_controller` is unset, `DiagnosticsController` falls bac
 
 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.
+
+## Failure detail is redacted
+
+Since 0.4.1, a failing check reports the exception **class** rather than its
+message:
+
+```json
+{ "name": "database", "critical": true, "status": "fail",
+  "error_class": "PG::ConnectionBad", "error_code": "pg_connection_bad" }
+```
+
+`/ready` is unauthenticated by design — probes carry no credentials — and a
+raw driver message will happily tell an anonymous caller the database host,
+port and username. The full message still reaches your logs and Sentry through
+the instrumentation below; it just isn't in the public body.
+
+```ruby
+c.expose_check_errors = true       # restore pre-0.4.1 verbose bodies
+c.detail_token = ENV["HEALTH_DETAIL_TOKEN"]   # X-Health-Token unlocks detail
+```
+
+`status`, `name`, `critical`, `latency_ms` and `generated_at` are unchanged.
+
+## Instrumentation
+
+The gem emits events on whichever bus is live — `Rails.event` on Rails 8.1+,
+`ActiveSupport::Notifications` otherwise:
+
+| Event | Payload |
+|---|---|
+| `standard_health.check.completed` | `name`, `critical`, `status`, `latency_ms`, `error_class`, `error_message` |
+| `standard_health.check.timed_out` | `name`, `critical`, `timeout_s` |
+| `standard_health.ready.evaluated` | `status`, `duration_ms`, `failed[]` |
+
+Three subscribers are registered automatically. Their noise profiles differ on
+purpose, because health events are **polls**, not state transitions — a 10s
+probe period means ~6 evaluations/minute/instance:
+
+- **Logger** — silent while healthy. `warn` on degraded, `error` on
+  unavailable. A line per evaluation would be ~8,640/day/instance of
+  "everything is fine".
+- **Sentry** — only on status **change**, plus a 60s repeat floor for a
+  sustained bad state, plus one `info` on recovery. Capturing every non-ok
+  poll would turn a five-minute outage into ~30 duplicate issues. Sentry is a
+  soft dependency; no gemspec entry.
+- **Metrics** — every poll, deliberately. Counters plus latency
+  distributions are what make `latency_ms` chartable.
+
+```ruby
+StandardHealth.configure do |c|
+  c.instrumentation_enabled = true    # default
+  c.logger        = Rails.logger      # default: Rails.logger
+  c.sentry_enabled = true             # default
+  c.metric_prefix  = "health"         # default
+
+  c.add_notifier(MyNotifier.new)      # must respond to call(event_name, payload)
+end
+```
+
+## Timeouts
+
+**Off by default.** Both settings are `nil`, which is byte-identical to 0.4.0.
+
+```ruby
+c.default_check_timeout = 2.0        # seconds, per check
+c.total_check_budget    = 5.0        # checked BEFORE each check starts
+c.register_check :db, MyCheck, critical: true, timeout: 1.0   # per-check override
+```
+
+**`total_check_budget` bounds how many checks RUN, not how long the probe
+takes.** It is evaluated before each check starts, not during one. With a 1s
+budget and a first check that blocks for 30s, `/ready` still takes 30s — only
+the checks *after* it are skipped.
+
+Clamping each check to the remaining budget would close that gap, and is
+deliberately not done: it would apply `Timeout.timeout` to checks whose author
+never asked for one, and that mechanism raises into the thread at an arbitrary
+point (see below). Setting a budget must not silently opt you into that. To
+bound wall-clock, put a `timeout:` on the checks that can safely take one.
+
+Enabling them is a semantic change — a check that has always been
+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*
+check could exhaust the budget, leave the database check unrun, and pull a
+healthy instance out of rotation.
+
+Checks run **sequentially**. They are not parallelised on purpose: running
+them in threads would mean connection checkouts from the health path, and a
+health endpoint that can exhaust the connection pool is a worse problem than
+the one it was added to solve.
+
+### ⚠ Know what `Timeout.timeout` actually does before enabling this
+
+Ruby's `Timeout.timeout` interrupts by raising **into the running thread at an
+arbitrary point**. It cannot wait for a safe boundary. If a timeout fires
+while a check is mid-way through a non-atomic operation — say a connection
+checkout in the `ActiveRecord` check — the connection can be returned to the
+pool in a broken state. You would have traded a slow check for a corrupted
+pool, on the health path, during an incident.
+
+The dedicated `CheckTimeout` class solves the *mislabelling* problem (a host's
+own `Timeout::Error` is never mistaken for ours). **It does not solve this
+one.** Nothing can, at this layer.
+
+So, before turning timeouts on:
+
+- Prefer a driver-level timeout where one exists — `connect_timeout` /
+  `statement_timeout` on the database, a client timeout on an HTTP dependency.
+  Those abort at a safe point because the driver owns the operation.
+- Reserve `timeout:` here for checks whose `run` is genuinely interruptible —
+  typically your own custom checks — rather than the built-in datastore ones.
+- Set the value comfortably above observed p99 (see the `latency_ms` in
+  `check.completed`), so it fires on a hang rather than on a slow day.
+
+This is why the defaults ship as `nil` and why choosing them is deferred: the
+right answer is usually a driver timeout, not this.
+
 ## License
 
 MIT.

data/app/controllers/standard_health/diagnostics_controller.rb

@@ -25,9 +25,36 @@ module StandardHealth
 
       render json: {
         mode: mode,
+        status: audit_status(audit),
         audit: audit,
         generated_at: Time.now.utc.iso8601
       }
     end
+
+    private
+
+    # Top-level verdict so a caller can gate on ONE field instead of
+    # re-implementing the roll-up over `audit`.
+    #
+    #   :ok         — no violations
+    #   :incomplete — at least one row is `:missing`, `:forbidden`, or
+    #                 `:mismatch` (`EnvSpec::VIOLATION_STATUSES`)
+    #
+    # The `forbidden`/`mismatch` statuses join the roll-up rather than
+    # getting a verdict of their own, so callers that already gate on
+    # `status == "incomplete"` pick up the new assertions for free. Note the
+    # level is deliberately NOT consulted: a `recommended` var declared with
+    # an `expected_value:` that does not hold is a failed assertion, not
+    # advice. The advisory status stays `:should_set`, which is not a
+    # violation.
+    #
+    # The endpoint still returns 200 either way, so nothing that asserts on
+    # the status code breaks.
+    def audit_status(audit)
+      violated = Array(audit).any? do |row|
+        EnvSpec::VIOLATION_STATUSES.include?(row[:status])
+      end
+      violated ? :incomplete : :ok
+    end
   end
 end