standard_health 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68d0908117b9ae70545445465e84f94b4c6ccc5ebecb2aa6ab05b3aafa5ba9f7
-  data.tar.gz: 52c3ffe85837e265283011db180de726957df2eecd09b971efc369e879ae4ec3
+  metadata.gz: 3d6a6ea3266864aaa15232529241e2040a836d810c4898eb512746e78a582901
+  data.tar.gz: fc9575f2c3e425a6065e3e5285094d03ba5cd694848c386937251b0fea5d75af
 SHA512:
-  metadata.gz: 379b80dbdf211c4c1a3e7639ec6cc926219949f9c352fbadddfada54bdea53f20df6ab52d5672baa0974bb6b2952b5f5e67b9069191d980baff1de0d3c77f972
-  data.tar.gz: feaba7a044e8e63e4dc60ad4d010edfbe197691596ea2520632c4d590f6e52907d9275a5825dea8deff42c716517cb569b54f2824460820327f5003e9e5b5157
+  metadata.gz: 83a04f1025e9e8b6e62344ff53828a716c262d7779d30f64afeb69b704fb34289e9138f751a93fb46215ba24c71612e17e9cfd7a37c859ac67feca64bbb2e25a
+  data.tar.gz: 6cf0b8d3a4100e8d3737eb1bbaddfb7c1a40d6dd77ad4e9c097ad547308ff196fb012b46ebb7c1d267b30d784abc863f734df4bd8520971d99af9d705e2af51b

data/CHANGELOG.md

@@ -7,6 +7,80 @@ 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

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:`
 
@@ -193,13 +302,31 @@ can gate on one field instead of re-implementing the roll-up:
 { "mode": "production", "status": "incomplete", "audit": [ ... ] }
 ```
 
-`incomplete` means at least one `required` var is missing; `recommended` is
-advisory and never affects it.
+`incomplete` means at least one row is a **violation** — `missing`,
+`forbidden`, or `mismatch`. `should_set` is advisory and never affects it.
 
-**The endpoint still returns 200 either way in 0.4.1.** That is deliberate: it
-gives monitors a release to migrate onto the field before 0.5.0 makes
-`incomplete` a 503. Flipping the status code without that window would
-silently redden every existing caller.
+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
 
@@ -223,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.

data/app/controllers/standard_health/diagnostics_controller.rb

@@ -36,19 +36,25 @@ module StandardHealth
     # Top-level verdict so a caller can gate on ONE field instead of
     # re-implementing the roll-up over `audit`.
     #
-    #   :ok         — nothing required is missing
-    #   :incomplete — at least one `required` var is missing
+    #   :ok         — no violations
+    #   :incomplete — at least one row is `:missing`, `:forbidden`, or
+    #                 `:mismatch` (`EnvSpec::VIOLATION_STATUSES`)
     #
-    # ADDITIVE ONLY in 0.4.1: the endpoint still returns 200 either way, so
-    # nothing that asserts on the status code breaks. That is the point —
-    # it gives monitors a release in which to migrate onto this field before
-    # 0.5.0 makes `:incomplete` a 503. Without the migration window, turning
-    # the code non-200 would silently redden every existing caller.
+    # 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)
-      incomplete = Array(audit).any? do |row|
-        row[:level].to_s == "required" && row[:status].to_s == "missing"
+      violated = Array(audit).any? do |row|
+        EnvSpec::VIOLATION_STATUSES.include?(row[:status])
       end
-      incomplete ? :incomplete : :ok
+      violated ? :incomplete : :ok
     end
   end
 end

data/lib/generators/standard_health/install/install_generator.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module StandardHealth
+  module Generators
+    # Installs StandardHealth in a host Rails application.
+    #
+    # Writes `config/initializers/standard_health.rb` and mounts the engine in
+    # `config/routes.rb`.
+    #
+    # The routes step exists because of a failure mode that is otherwise
+    # invisible: the engine only draws SUB-paths (`/alive`, `/ready`,
+    # `/diagnostics/env`), so an app that mounts it and expects an aggregate
+    # `GET /health` silently has no aggregate tier — no boot error, no failing
+    # route spec. The generated block carries the ordering requirement as a
+    # comment right where someone will read it.
+    #
+    # Idempotent: re-running skips pieces already installed. `--skip-*` opts
+    # out of individual steps; `--force` overwrites an existing initializer.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      INITIALIZER_PATH = "config/initializers/standard_health.rb"
+      ROUTES_PATH = "config/routes.rb"
+
+      desc <<~DESC
+        Installs StandardHealth. By default this:
+          * writes config/initializers/standard_health.rb
+          * mounts StandardHealth::Engine in config/routes.rb, with the
+            aggregate-route ordering requirement noted inline
+
+        Use --skip-* flags to opt out of individual steps when re-running on an
+        existing install. The generator is idempotent — already-installed
+        pieces are skipped with a clear message. Pass --force to overwrite an
+        existing initializer.
+      DESC
+
+      class_option :skip_initializer, type: :boolean, default: false,
+        desc: "Do not write #{INITIALIZER_PATH}"
+      class_option :skip_routes, type: :boolean, default: false,
+        desc: "Do not mount the engine in #{ROUTES_PATH}"
+      class_option :force, type: :boolean, default: false,
+        desc: "Overwrite #{INITIALIZER_PATH} if it already exists"
+
+      def copy_initializer
+        if options[:skip_initializer]
+          say_status("skip", "#{INITIALIZER_PATH} (--skip-initializer)", :yellow)
+          return
+        end
+
+        if File.exist?(File.join(destination_root, INITIALIZER_PATH)) && !options[:force]
+          say_status("identical", "#{INITIALIZER_PATH} (already exists; pass --force to overwrite)", :blue)
+          return
+        end
+
+        template "initializer.rb.erb", INITIALIZER_PATH, force: options[:force]
+      end
+
+      def mount_engine
+        if options[:skip_routes]
+          say_status("skip", "#{ROUTES_PATH} (--skip-routes)", :yellow)
+          return
+        end
+
+        unless routes_file_exists?
+          say_status("skip", "#{ROUTES_PATH} not found; mount the engine manually", :yellow)
+          return
+        end
+
+        if already_mounted?
+          say_status("identical", "#{ROUTES_PATH} (engine already mounted), skipping", :blue)
+          return
+        end
+
+        route(routes_snippet)
+
+        return unless aggregate_route_drawn?
+
+        # `route` prepends, so a host that already draws its own `GET /health`
+        # ends up with the mount ABOVE it. That still WORKS — the engine draws
+        # no bare `/health`, so its router returns X-Cascade: pass and the
+        # outer route matches (there is a spec pinning this). But it reads
+        # backwards against the documented ordering, so say so rather than
+        # leaving them to wonder.
+        say_status(
+          "review",
+          "#{ROUTES_PATH}: the mount was prepended ABOVE your existing `GET /health`. " \
+          "It still resolves via route cascading, but move the mount below it to match " \
+          "the documented ordering.",
+          :yellow
+        )
+      end
+
+      no_commands do
+        def routes_file_exists?
+          File.exist?(File.join(destination_root, ROUTES_PATH))
+        end
+
+        def routes_source
+          File.read(File.join(destination_root, ROUTES_PATH))
+        end
+
+        # Match the mount however it was written — `=>` or a trailing `at:` —
+        # so a hand-mounted app isn't given a duplicate.
+        #
+        # ANCHORED PER LINE, and that matters: an unanchored match would treat
+        # a commented example (`# mount StandardHealth::Engine => "/health"`)
+        # as a live mount and skip the install, leaving the host with no health
+        # routes at all and a "already mounted, skipping" message explaining
+        # why it was fine.
+        def already_mounted?
+          routes_source.each_line.any? do |line|
+            line.match?(/\A\s*mount\s+StandardHealth::Engine/)
+          end
+        end
+
+        # Does the host already draw its own aggregate `GET /health`? Same
+        # per-line anchoring, for the same reason.
+        def aggregate_route_drawn?
+          routes_source.each_line.any? do |line|
+            line.match?(%r{\A\s*(?:get|match)\s+["']/health["']})
+          end
+        end
+
+        # `route` prepends, so this block lands at the top of the draw block.
+        # The aggregate line is commented rather than generated live: the
+        # engine ships no aggregate controller (the tier is the host's job,
+        # and its target is host-specific — often standard_circuit's), so
+        # generating a route to a controller that does not exist would break
+        # boot. The comment is the deliverable here.
+        def routes_snippet
+          <<~ROUTES
+            # StandardHealth — liveness, readiness and the env doctor.
+            #
+            # ORDERING MATTERS. The aggregate `GET /health` must be drawn
+            # BEFORE the mount below. The engine draws only sub-paths
+            # (/alive, /ready, /diagnostics/env), so an app that mounts first
+            # and relies on the engine to serve the aggregate tier silently
+            # has NO aggregate tier — no boot error, no failing route spec.
+            #
+            # Uncomment and point at your aggregate controller:
+            # get "/health", to: "health_aggregate#show"
+            mount StandardHealth::Engine => "/health", as: :standard_health
+          ROUTES
+        end
+      end
+    end
+  end
+end

data/lib/generators/standard_health/install/templates/initializer.rb.erb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# StandardHealth configuration.
+#
+# ── ROUTE ORDERING (read this before touching config/routes.rb) ─────────────
+#
+# The engine draws SUB-paths only: /alive, /ready, /diagnostics/env. The
+# aggregate `GET /health` is the HOST's responsibility, and it must be drawn
+# BEFORE the mount:
+#
+#   get "/health", to: "health_aggregate#show"          # aggregate — FIRST
+#   mount StandardHealth::Engine => "/health", as: :standard_health
+#
+# An app that mounts the engine first and expects it to serve the aggregate
+# tier silently has no aggregate tier at all — no boot error, and no failing
+# route spec unless one exists. Add a route spec for `GET /health`.
+#
+# Tiers: /alive = liveness (process up) · /ready = readiness (rotation gate)
+# /health = aggregate (dashboards) · /diagnostics/env = authed doctor.
+# ────────────────────────────────────────────────────────────────────────────
+
+StandardHealth.configure do |config|
+  # Controller the engine's controllers inherit from. Defaults to
+  # ActionController::API so the engine works unconfigured in API-only apps.
+  # config.parent_controller = "ApplicationController"
+
+  # /diagnostics/env enumerates which env vars are missing or wrong — protect
+  # it. Setting a diagnostics-only parent lets you put auth on the doctor tier
+  # without the callback leaking onto /alive and /ready.
+  # config.diagnostics_parent_controller = "DiagnosticsBaseController"
+
+  # ── Checks ───────────────────────────────────────────────────────────────
+  #
+  # READINESS GATES ONLY ON HARD INFRA THIS APP OWNS. A failing critical check
+  # pulls the instance out of rotation, so `critical: true` belongs on the
+  # database and little else. Soft upstreams degrade; they never gate rotation.
+  config.register_check :database, StandardHealth::Checks::ActiveRecord, critical: true
+  # config.register_check :cache, StandardHealth::Checks::SolidCache
+  # config.register_check :queue, StandardHealth::Checks::SolidQueue
+
+  # Opt-in checks — not registered by default. Uncomment what applies.
+  #
+  # SolidCable: probes the `solid_cable_messages` store. Prefer this on the
+  # AGGREGATE tier; a broken cable store should degrade, not de-rotate.
+  # config.register_check :solid_cable, StandardHealth::Checks::SolidCable
+  #
+  # EnvSpecAudit: surfaces the env_spec below as a health check, failing on
+  # :missing / :forbidden / :mismatch rows. This is how config drift becomes
+  # visible without anyone polling the authed doctor endpoint. Non-critical by
+  # default on purpose — drift is a warning, not a reason to stop serving.
+  # config.register_check :env_spec, StandardHealth::Checks::EnvSpecAudit
+
+  # ── Timeouts ─────────────────────────────────────────────────────────────
+  #
+  # Both OFF by default. Read the README's Timeout.timeout caveat before
+  # enabling: it raises into the thread at an arbitrary point and can return a
+  # broken connection to the pool. A driver-level timeout is almost always the
+  # better tool.
+  # config.default_check_timeout = 2
+  # config.total_check_budget = 5
+
+  # ── Env spec ─────────────────────────────────────────────────────────────
+  #
+  # Declare what this app needs from its environment. Audited by
+  # /diagnostics/env, and by the EnvSpecAudit check above if registered.
+  config.env_spec = StandardHealth::EnvSpec.define do
+    # Reusable groupings of APP_ENVIRONMENT values, referenced as Symbols in `in:`.
+    mode_alias :deployed, %w[staging preview production]
+    mode_alias :live, %w[production]
+
+    group "Core" do
+      required :SECRET_KEY_BASE
+      required :DATABASE_URL, in: :deployed
+    end
+
+    group "Observability" do
+      recommended :SENTRY_DSN,
+        description: "Error tracking DSN (unique per environment)",
+        consumed_by: "config/initializers/sentry.rb"
+    end
+
+    # `forbidden` inverts the presence rule: absent is :ok, present is
+    # :forbidden. This is the level for dangerous toggles that are fine on
+    # staging and must never survive promotion — no custom check needed.
+    # group "Production-forbidden toggles" do
+    #   forbidden :DEMO_MODE_ENABLED, in: :live,
+    #     description: "Demo surfaces; unset before promoting"
+    #   forbidden :BOOTSTRAP_NEEDED, in: :live,
+    #     description: "First-boot admin bootstrap; unset once an admin exists"
+    # end
+
+    # `expected_value:` asserts the VALUE, not just presence. A present value
+    # that does not match reports :mismatch. Accepts a String, an Array
+    # ("any of"), or a Regexp.
+    # required :CONTENT_SECURITY_POLICY_REPORT_ONLY, in: :live,
+    #   expected_value: "false",
+    #   description: "Any other value leaves the CSP report-only"
+  end
+end

data/lib/standard_health/checks/env_spec_audit.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "standard_health/check"
+require "standard_health/env_spec"
+
+module StandardHealth
+  module Checks
+    # Surfaces EnvSpec violations as a health check.
+    #
+    # WHY THIS EXISTS
+    #
+    # The env-spec audit is otherwise only visible on `/diagnostics/env`,
+    # which is authed and polled by nobody. So hosts that wanted config drift
+    # to show up on a health tier wrote their own check to re-derive it —
+    # fundbright-web carried two (`ForbiddenToggles`, `CspEnforcement`) built
+    # from hand-maintained constant lists that had to be kept in sync with the
+    # env spec by comment. This check reads the spec directly, so there is one
+    # declaration and no list to drift.
+    #
+    # NOT REGISTERED AUTOMATICALLY. See `Checks::SolidCable` for the reasoning
+    # — briefly: auto-registering would fail existing hosts on a `bundle
+    # update` the moment their spec had any pre-existing violation.
+    #
+    # Register it yourself:
+    #
+    #   c.register_check :env_spec, StandardHealth::Checks::EnvSpecAudit
+    #
+    # 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 pulling it out of rotation
+    # would convert a warning into an outage. It rolls the aggregate up to
+    # `:degraded` (HTTP 200). Registering it `critical: true` means "this app
+    # must not serve at all with a bad env", which is a real but rare posture
+    # — and on the readiness tier it will pull instances. Know which you want.
+    #
+    # To narrow what counts as a failure, or to make it critical, subclass —
+    # the aggregator instantiates checks with `name:`/`critical:` only, so
+    # per-registration options are not available:
+    #
+    #   class StrictEnvSpec < StandardHealth::Checks::EnvSpecAudit
+    #     def initialize(name: :env_spec, critical: false)
+    #       super(name: name, critical: critical, fail_on: %i[forbidden])
+    #     end
+    #   end
+    class EnvSpecAudit < Check
+      # Reported as `error_class` so the redacted body carries a groupable
+      # `error_code` (`standard_health_env_spec_violation`) instead of a
+      # meaningless "StandardError". Not an exception class — nothing here
+      # raises — just a stable label.
+      VIOLATION_LABEL = "StandardHealth::EnvSpecViolation"
+
+      def initialize(name: :env_spec, critical: false, fail_on: EnvSpec::VIOLATION_STATUSES)
+        super(name: name, critical: critical)
+        @fail_on = Array(fail_on).map(&:to_sym)
+      end
+
+      # @return [Array<Symbol>] audit statuses this check treats as failures
+      attr_reader :fail_on
+
+      def run
+        violations = nil
+
+        # `with_timing` is what keeps the never-raise invariant: `audit` runs
+        # host-supplied `if:`/`unless:` procs and can raise `UnknownModeAlias`,
+        # and neither may reach the aggregator as an exception.
+        timing = with_timing { violations = violating_rows }
+
+        return timing unless timing[:status] == :ok
+        return timing if violations.empty?
+
+        timing.merge(
+          status: :fail,
+          error: describe(violations),
+          error_class: VIOLATION_LABEL
+        )
+      end
+
+      private
+
+      def violating_rows
+        spec = ::StandardHealth.config.env_spec
+        return [] unless spec
+
+        # No `root:`. Resolving `consumed_by` paths does file IO per entry,
+        # which is fine for an on-demand doctor endpoint and not fine on a
+        # health tier that gets polled every few seconds. Consumer presence is
+        # a code-review question anyway, not a runtime health signal.
+        spec.audit(ENV.to_h, mode: ENV["APP_ENVIRONMENT"].to_s)
+            .select { |row| @fail_on.include?(row[:status]) }
+      end
+
+      # Names only, grouped by status. Env var NAMES are not secrets and are
+      # the whole point of the message; VALUES never appear. This message is
+      # redacted out of an unauthenticated /ready body anyway and reaches
+      # operators via the instrumentation events.
+      def describe(violations)
+        violations
+          .group_by { |row| row[:status] }
+          .sort_by { |status, _| status.to_s }
+          .map { |status, rows| "#{status}: #{rows.map { |r| r[:name] }.sort.join(', ')}" }
+          .join("; ")
+      end
+    end
+  end
+end

data/lib/standard_health/checks/solid_cable.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "standard_health/check"
+
+module StandardHealth
+  module Checks
+    # Verifies the SolidCable / ActionCable backing store is reachable.
+    #
+    # SolidCable persists messages in `solid_cable_messages`. The probe is a
+    # bounded read against that table, which confirms both that the cable
+    # schema is migrated and that the connection it lives on is up.
+    #
+    # Promoted from sidekick-web's `SolidCableCheck`, which was one of four
+    # host-local copies of a check the gem should have shipped.
+    #
+    # NOT REGISTERED AUTOMATICALLY. Registering it would be a behaviour change
+    # on `bundle update`: every host without SolidCable installed — or with the
+    # table not yet migrated — would start reporting a failing check, turning
+    # the aggregate tier yellow across the estate for a check nobody asked for.
+    # New checks in this gem are opt-in for that reason.
+    #
+    #   c.register_check :solid_cable, StandardHealth::Checks::SolidCable
+    #
+    # NON-CRITICAL BY DEFAULT, deliberately: cable is a degradable feature
+    # dependency. A broken cable store should mark the app `degraded`, never
+    # pull an instance out of rotation — so prefer this on the AGGREGATE tier
+    # rather than in readiness.
+    class SolidCable < Check
+      def initialize(name: :solid_cable, critical: false)
+        super
+      end
+
+      def run
+        with_timing do
+          connection.select_value("SELECT 1 FROM solid_cable_messages LIMIT 1")
+        end
+      end
+
+      private
+
+      # SolidCable may or may not be pointed at a separate database
+      # (`SolidCable::Record.connects_to`). When it isn't configured, the table
+      # lives on the primary connection, so fall back to it rather than failing
+      # a host that simply didn't split the database out.
+      def connection
+        if defined?(::SolidCable::Record) && ::SolidCable::Record.respond_to?(:connection)
+          ::SolidCable::Record.connection
+        else
+          ::ActiveRecord::Base.connection
+        end
+      end
+    end
+  end
+end

data/lib/standard_health/configuration.rb

@@ -93,8 +93,9 @@ module StandardHealth
     #
     # The machinery ships now so apps can opt in per check and so the events
     # emitted in this release can tell us what the real p99 latencies are.
-    # Sensible defaults get chosen from that data in 0.5.0, which requires an
-    # explicit Gemfile edit.
+    # Sensible defaults get chosen from that data in a later release, once
+    # enough p99 data has accumulated to pick them from evidence rather than
+    # guesswork — deliberately NOT 0.5.0, which shipped without it.
     attr_accessor :default_check_timeout
 
     # Budget across all checks, evaluated BEFORE each check starts. Checks not

data/lib/standard_health/env_spec.rb

@@ -12,6 +12,8 @@ module StandardHealth
   #     required :SECRET_KEY_BASE
   #     required :APP_ENVIRONMENT, in: %w[staging production]
   #     recommended :SENTRY_DSN, description: "Error tracking DSN"
+  #     forbidden :DEMO_MODE_ENABLED, in: :live
+  #     required :CSP_REPORT_ONLY, in: :live, expected_value: "false"
   #
   #     group "Singpass / MyInfo" do
   #       required :MYINFO_CLIENT_ID
@@ -23,7 +25,7 @@ module StandardHealth
   #
   # Each entry has:
   #   - `name` (Symbol)
-  #   - `level` (:required | :recommended)
+  #   - `level` (:required | :recommended | :forbidden)
   #   - `in:` (Array<String>, Symbol, or nil) — when an Array, the entry only
   #     applies while `APP_ENVIRONMENT` matches one of these modes. A Symbol
   #     is resolved against `mode_alias` declarations at audit time. When
@@ -47,11 +49,28 @@ module StandardHealth
   #     Surfaced verbatim in audit rows.
   #   - `replacement:` (String, optional) — what to use instead. Surfaced
   #     in audit rows.
+  #   - `expected_value:` (String/Symbol/Numeric/Regexp/Array, optional) —
+  #     asserts the *value*, not just presence. A present value that does
+  #     not match reports `status: :mismatch`. An Array means "any of".
+  #     Surfaced in audit rows as `expected_value:` so an operator can see
+  #     what was demanded; the actual value is deliberately NEVER surfaced
+  #     (env values are frequently secrets).
   class EnvSpec
     # Raised when `in:` references a Symbol that hasn't been declared via
     # `mode_alias`.
     class UnknownModeAlias < ArgumentError; end
 
+    # Levels whose absence is fine and whose *presence* is the failure.
+    FORBIDDEN_LEVEL = :forbidden
+
+    # Statuses that mean the environment is wrong, as opposed to merely
+    # advisory (`:should_set`) or inapplicable (`:not_applicable`).
+    #
+    # Shared by `DiagnosticsController#audit_status` and the opt-in
+    # `Checks::EnvSpecAudit`, so the doctor endpoint and the health check
+    # cannot drift apart on what counts as a violation.
+    VIOLATION_STATUSES = %i[missing forbidden mismatch].freeze
+
     # Internal entry record. `modes` may be an Array<String> or a Symbol
     # alias that gets resolved at audit time.
     Entry = Struct.new(
@@ -66,6 +85,7 @@ module StandardHealth
       :deprecated,
       :sunset_on,
       :replacement,
+      :expected_value,
       keyword_init: true
     )
 
@@ -128,6 +148,31 @@ module StandardHealth
       add(:recommended, name, **opts)
     end
 
+    # Declare an env var that must NOT be set (in the applicable modes).
+    # Inverts the presence rule: absent is `:ok`, present is `:forbidden`.
+    #
+    # This is the level for dangerous ops toggles — demo modes, auth
+    # bypasses, bootstrap flags — that are legitimate on staging and must
+    # never survive to production:
+    #
+    #   forbidden :DEMO_MODE_ENABLED, in: :live,
+    #     description: "Demo surfaces; unset before promoting"
+    #
+    # `expected_value:` is meaningless here (the assertion is "absent"), so
+    # combining them is a declaration error rather than a silently ignored
+    # option. Raised at `define` time — i.e. host boot, well off the health
+    # path — so it can never surface as a 500 from /ready.
+    def forbidden(name, **opts)
+      if opts.key?(:expected_value)
+        raise ArgumentError,
+              "`forbidden` asserts absence, so expected_value: is meaningless " \
+              "(got #{opts[:expected_value].inspect} for #{name}). Use " \
+              "`required ..., expected_value:` to assert a value instead."
+      end
+
+      add(FORBIDDEN_LEVEL, name, **opts)
+    end
+
     # Run the audit against an env-like hash.
     #
     # @param env_hash [Hash{String, Symbol => String}] e.g. ENV.to_h
@@ -143,8 +188,8 @@ module StandardHealth
     #   least `name`, `level`, `status`, `mode`. When an entry is suppressed
     #   by an `if:`/`unless:` predicate, `status` is `:not_applicable` and a
     #   `reason` field explains why. `description`, `consumed_by`, `group`,
-    #   `deprecated`, `sunset_on`, `replacement`, and `consumer` are
-    #   included when set on the entry / computed during audit.
+    #   `deprecated`, `sunset_on`, `replacement`, `expected_value`, and
+    #   `consumer` are included when set on the entry / computed during audit.
     def audit(env_hash, mode:, root: nil)
       mode_str = mode.to_s
       env = stringify(env_hash)
@@ -185,7 +230,8 @@ module StandardHealth
         group: @group_stack.last,
         deprecated: opts[:deprecated] ? true : nil,
         sunset_on: opts[:sunset_on],
-        replacement: opts[:replacement]
+        replacement: opts[:replacement],
+        expected_value: opts[:expected_value]
       )
     end
 
@@ -241,9 +287,28 @@ module StandardHealth
       row[:deprecated] = true if entry.deprecated
       row[:sunset_on] = entry.sunset_on.to_s if entry.sunset_on
       row[:replacement] = entry.replacement if entry.replacement
+      # The DECLARED expectation is safe to surface — it is config the host
+      # wrote, not process state. The ACTUAL value is never surfaced: env
+      # values are routinely secrets, and /diagnostics/env exists to report
+      # that something is wrong, not to echo it back.
+      row[:expected_value] = serialize_expected(entry.expected_value) unless entry.expected_value.nil?
       row
     end
 
+    # Regexps have to become strings to survive JSON rendering; an Array of
+    # candidates stays an Array so a caller can see every accepted value.
+    def serialize_expected(expected)
+      if expected.is_a?(Array)
+        expected.map { |candidate| stringify_expected(candidate) }
+      else
+        stringify_expected(expected)
+      end
+    end
+
+    def stringify_expected(candidate)
+      candidate.is_a?(Regexp) ? candidate.inspect : candidate.to_s
+    end
+
     # Resolve the consumer-presence state for an entry. Returns nil when
     # we have nothing to check (no root, no consumed_by). Otherwise:
     #
@@ -283,11 +348,48 @@ module StandardHealth
       value.length == 1 ? value.first : value
     end
 
+    # Resolve one entry against the value found in the env.
+    #
+    #   :forbidden  — a `forbidden` entry is set
+    #   :missing    — a `required` entry is absent
+    #   :should_set — a `recommended` entry is absent
+    #   :mismatch   — present, but `expected_value:` says otherwise
+    #   :ok         — everything else
+    #
+    # Presence is checked first for every level, because "absent" is
+    # unambiguous: it satisfies `forbidden`, violates `required`, and there
+    # is nothing for `expected_value:` to compare against.
     def classify(entry, value)
       present = !value.nil? && !value.to_s.empty?
-      return :ok if present
 
-      entry.level == :required ? :missing : :should_set
+      if entry.level == FORBIDDEN_LEVEL
+        return present ? :forbidden : :ok
+      end
+
+      unless present
+        return entry.level == :required ? :missing : :should_set
+      end
+
+      return :mismatch unless expected_value_satisfied?(entry, value)
+
+      :ok
+    end
+
+    # Compare a present value against `expected_value:`. Comparison is on
+    # the string form, since everything arriving from ENV is a String —
+    # `expected_value: 5` matching `"5"` is the intuitive reading, and the
+    # alternative (never matching) would be a silent trap.
+    #
+    # An Array means "any of". A Regexp is matched, not compared, which is
+    # what makes value ranges and prefixes expressible.
+    def expected_value_satisfied?(entry, value)
+      expected = entry.expected_value
+      return true if expected.nil?
+
+      actual = value.to_s
+      Array(expected).any? do |candidate|
+        candidate.is_a?(Regexp) ? candidate.match?(actual) : candidate.to_s == actual
+      end
     end
 
     def stringify(env_hash)

data/lib/standard_health/version.rb

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

data/lib/standard_health.rb

@@ -8,6 +8,10 @@ require "standard_health/check"
 require "standard_health/checks/active_record"
 require "standard_health/checks/solid_queue"
 require "standard_health/checks/solid_cache"
+# Opt-in checks — required so the constants resolve, NOT registered. See each
+# class for why auto-registration would break existing hosts on bundle update.
+require "standard_health/checks/solid_cable"
+require "standard_health/checks/env_spec_audit"
 require "standard_health/event_emitter"
 require "standard_health/notifiers/logger"
 require "standard_health/notifiers/sentry"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_health
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -13,14 +13,14 @@ dependencies:
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
 description: StandardHealth is a mountable Rails engine providing /alive, /ready,
@@ -41,10 +41,14 @@ files:
 - app/controllers/standard_health/diagnostics_controller.rb
 - app/controllers/standard_health/health_controller.rb
 - config/routes.rb
+- lib/generators/standard_health/install/install_generator.rb
+- lib/generators/standard_health/install/templates/initializer.rb.erb
 - lib/standard_health.rb
 - lib/standard_health/aggregator.rb
 - lib/standard_health/check.rb
 - lib/standard_health/checks/active_record.rb
+- lib/standard_health/checks/env_spec_audit.rb
+- lib/standard_health/checks/solid_cable.rb
 - lib/standard_health/checks/solid_cache.rb
 - lib/standard_health/checks/solid_queue.rb
 - lib/standard_health/configuration.rb