standard_circuit 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e92eb79ddb1cfc0f2e9221aa62f45d7c304df0dfea22c114eb31a78c071b6c3c
-  data.tar.gz: 0aac1e3c093805ea2825cfb434840d83842999cb757cdcca896466c86a6abbff
+  metadata.gz: ac355e3881c42900c272ba14d433216f4d8e6019e003e4b5bd52f84545c11c79
+  data.tar.gz: ffdb732b389d5b752deef02d6cdc82fd148af38e3e861d046876cce329e50d36
 SHA512:
-  metadata.gz: 9e5ac3bb1d7352c6300fa70530602910dd3a45539e1cfad5d45b8ac702a223a22961cdaef377daf7c968ad7bbb5db54814c70a40b1a054a41df88c15fc5908c2
-  data.tar.gz: e8f4b265dd59f67442b52fafdb4db15923236df241b4296adc80bb6576654a888cdc564a5c2aa36e9ad291f5720f0c7fae7a274edcce046bb6995b6fbcb04dc7
+  metadata.gz: e2ffa97cfc68660ca8e32bd606df2251700f619f728969ce0e27ed485b6887eb6d8ecd6f1b641a0cea9d22c4842c3a5041a25b00bac97a84c37ea00ca78adf48
+  data.tar.gz: 8f245331cafaeb355b33e0ddd515bb23824713826d908544533959cd1f2dcb6c21d0160887370dadeef566a495d0474f66603095c0e1d93d1275f67c35f9f27d

data/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-30
+
+### Added
+- `config.sentry_criticality_levels` — opt in to criticality-aware Sentry reporting for the built-in Sentry subscriber. Accepts `true` (the recommended map `{ critical: :error, standard: :warning, optional: :info }`), a partial Hash merged over that map, or `nil` / `false` for the previous flat behaviour. In criticality-aware mode a circuit-open report also gains `circuit` / `circuit_criticality` tags and a stable `["circuit-open", <circuit>]` fingerprint, so Sentry alert rules can page on `circuit_criticality:critical` and group one issue per breaker. Invalid criticalities and non-symbolizable levels raise `ArgumentError` at configure time rather than failing silently at alert time.
+
+  **This is opt-in, and deliberately not the new default.** Both the level and the fingerprint feed Sentry's alerting and issue grouping, so flipping the map on at gem-upgrade time would silently re-page and re-group live issues in apps that never asked for it. Apps that leave `sentry_criticality_levels` unset get the 0.2.x report byte-for-byte — same `:warning` level, same message, no tags, no fingerprint. Host apps that hand-rolled this by setting `sentry_enabled = false` and registering their own alerter can now delete that class and set `sentry_enabled = true` + `sentry_criticality_levels = true` instead.
+- `isolate_namespace StandardCircuit` on the engine, bringing it in line with every other engine gem in the family. Verified non-breaking for the aggregate health route every consumer draws (`get "/health", to: "standard_circuit/health#show"`): that path is resolved by the *application's* route set through constant lookup, which isolation does not touch, and the new `spec/integration/health_route_boot_spec.rb` boots a real Rails app and requests the route end to end so a regression fails here rather than in a consumer after release. Safe specifically because this engine is library-only — no `config/routes.rb` for the isolated `default_scope` to scope, and no ActiveRecord models for the `standard_circuit_` `table_name_prefix` to apply to.
+
+  One consequence to know about: `StandardCircuit::HealthController` now picks up the engine's (empty) url helpers instead of the application's, so app path helpers used inside it — or inside a host subclass of it — need a `main_app.` prefix. The gem's controller only renders JSON, so nothing in-gem is affected.
+- README section on `data_store`, previously undocumented. Spells out that the `Stoplight::DataStore::Memory` default is **per-process** — thresholds count per worker, `/health` reports the serving process's view, and `force_open` / `reset!` are process-local — plus the shared-store alternative for apps that want cross-process state.
+- README section on Sentry reporting covering `sentry_enabled`, the new `sentry_criticality_levels` opt-in, and the "subscribe yourself" escape hatch.
+
+### Changed
+- The install generator now warns that the aggregate `get "/health", to: "standard_circuit/health#show"` route must be drawn **before** `mount StandardHealth::Engine => "/health"`. `StandardHealth::Engine` registers sub-paths only (`/alive`, `/ready`, `/diagnostics/env`) and never serves the aggregate tier itself, so an app that mounts it and assumes `/health` is covered silently has no aggregate tier — with no boot error and no failing route spec to reveal it. The warning appears in the initializer template, in the `--with-health-endpoint` health initializer next to the route line, and in the hint the generator prints. Same note added to the README's health-endpoint section.
+- `.github/workflows/ci.yml` follows the shared reusable workflow at `@v2` again, matching the rest of the gem family. The previous SHA pin carried a stale rationale: it claimed to restore pre-`rarebit-one/.github#14` job names for branch protection, but `main`'s protection now requires the *post*-#14 names (`ci / lint`, `ci / test-matrix (4.0.x)`) and the pinned revision's `reusable-gem-ci.yml` is byte-identical to `@v2` — so it was neither restoring old names nor changing any check name. It did honour `extra-lint-commands`, so the brakeman / bundler-audit gate was live throughout.
+
+## [0.2.0] - 2026-04-28
+
+### Added
+- Rails event emission for every circuit-breaker lifecycle moment. The `StandardCircuit::Runner` (via a small internal `NotifierBridge` registered with Stoplight) now emits five events as host apps' breakers change state:
+  - `standard_circuit.circuit.opened` — RED transition (the "alert me" event)
+  - `standard_circuit.circuit.closed` — GREEN transition (recovery)
+  - `standard_circuit.circuit.degraded` — YELLOW transition (half-open probe)
+  - `standard_circuit.circuit.fallback_invoked` — Runner returned a fallback rather than raising RedLight
+  - `standard_circuit.circuit.registered` — `Config#register` / `register_prefix` was called
+
+  Payloads carry `circuit:`, `from_color:`, `to_color:`, `criticality:`, and (when applicable) `error_class:` / `error_message:` / `reason:`.
+- `standard_circuit.run.completed` event. Per-call complement to the lifecycle events above — fires once per wrapped `StandardCircuit.run` invocation with `circuit:`, `status:` (`:success` / `:failure` / `:circuit_open`), `duration_ms:`, `criticality:`, `error_class:`, and `error_message:`. The right hook for cost-tracking, p95 latency, and per-circuit success-rate dashboards. (`force_closed` runs are intentionally not emitted — that path bypasses the runner.) Routed through the same `EventEmitter` as the lifecycle events, so subscribers get it on `Rails.event` (8.1+) or `ActiveSupport::Notifications` automatically; `duration_ms` is in the payload (not `event.duration`) so backend choice doesn't matter.
+- Dual-backend dispatch in `StandardCircuit::EventEmitter`: emits through `Rails.event.notify` on Rails 8.1+ and falls back to `ActiveSupport::Notifications.instrument` on older Rails. Detection happens at call time, so the gem still loads cleanly before Rails has booted and before `railties` is even required.
+- `StandardCircuit::Engine` Railtie that registers the internal subscribers (Logger / Sentry / Metrics) plus any `extra_notifiers` at boot via the `standard_circuit.subscribers` initializer.
+- `StandardCircuit.subscribers` accessor + `Subscribers#setup!` / `#teardown!` for tests and host apps that need to re-register listeners after mutating config.
+- `rails g standard_circuit:install` — Rails install generator. Writes `config/initializers/standard_circuit.rb` with commented-out examples covering the public Config DSL (`register`, `register_prefix`, notifiers, data store, criticality). Idempotent: re-running on an existing initializer skips with a clear message; pass `--force` to overwrite. Pass `--with-health-endpoint` to also write `config/initializers/standard_circuit_health.rb` (which `require`s the opt-in `HealthController`) and print the route line to add to `config/routes.rb`. The generator does not auto-edit `routes.rb` — too invasive — so consumers paste the printed line themselves.
+- README section on streaming responses and non-controller contexts: shows the recipe for catching `Stoplight::Error::RedLight` inside a `Live` controller's streaming proc (where `circuit_open_fallback` can't render over an open response), and notes the equivalent pattern for background jobs.
+
+### Changed
+- **BREAKING.** `StandardCircuit::Notifiers::{Logger,Sentry,Metrics}` are no longer Stoplight-shaped notifiers. Each now exposes `call(event_name, payload)` and is registered as an event subscriber by the gem's Railtie. They are still considered an internal implementation detail — host apps that want their own behaviour should subscribe to the `standard_circuit.*` namespace directly rather than instantiating these classes.
+- **BREAKING.** `Config#add_notifier` now requires the supplied object to respond to `call(event_name, payload)`. Stoplight-shaped 4-arg notifiers from 0.1.x are rejected with `ArgumentError`. Callers should subscribe via `Rails.event.subscribe` / `ActiveSupport::Notifications.subscribe("standard_circuit.*")` for full control, or pass a lambda to `add_notifier` for the simple case.
+- **BREAKING.** Stoplight only sees a single internal `StandardCircuit::NotifierBridge` notifier now; host apps that previously read `StandardCircuit.config.notifiers` to build their own Stoplight light will need to register against the new event namespace instead.
+- README "Quick start" and the `rails g standard_circuit:install` initializer template now use `ErrorTaxonomies::*.tracked` consistently (the S3 example in the template still showed the pre-0.1.2 `AdapterErrors::Aws.server_errors` form).
+- The install template's "Extra notifiers" example now uses `add_notifier` with a 2-arg `call(name, payload)` callable, matching the contract `Config#add_notifier` enforces. The previous example wrote directly to `extra_notifiers <<` with a 1-arg lambda — both bypassing validation and using the wrong arity, so any consumer who uncommented it would get `ArgumentError: wrong number of arguments` on the first emitted event.
+- `lib/standard_circuit/rspec.rb` now also tears down event subscribers between examples so a spec that subscribes manually doesn't leak listeners into the next.
+- CI and release workflows migrated to the shared `rarebit-one/.github` reusable workflows (`reusable-gem-ci.yml@v1`, `reusable-gem-release.yml@v1`); `.github/workflows/ci.yml` and `release.yml` are now thin shims.
+
 ## [0.1.2] - 2026-04-27
 
 ### Added
@@ -37,6 +80,7 @@ All notable changes to this project will be documented in this file.
 - `StandardCircuit.force_open`, `force_closed`, `reset_force!` + `require "standard_circuit/rspec"` for auto-cleanup.
 
 ### Changed
+- Minimum Ruby version is now `>= 4.0` (was `>= 3.4`). CI tests all four published 4.0.x patches.
 - Removed redundant `defined?(::Sentry::Metrics)` guards in `Runner`, `ControllerSupport`, and `Notifiers::Metrics`. `sentry-ruby` is a hard runtime dependency; the guards were dead code.
 - Tightened `sentry-ruby` lower bound from `>= 5.0` to `>= 5.17`. `Sentry::Metrics` was introduced in 5.17; the previous floor let Bundler resolve a version where the metrics API does not exist.
 

data/LICENSE

@@ -0,0 +1,22 @@
+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
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+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.

data/README.md

@@ -6,7 +6,7 @@ Wraps the upstream `stoplight` gem with:
 
 - Opinionated default error taxonomy (network errors track; caller/config errors do not)
 - SDK-specific adapter error bundles (Stripe, AWS, Faraday, SMTP)
-- Sentry notifier (warning on GREEN→RED) and metrics notifier (`external.circuit_breaker`, `external.request`)
+- Rails event emission (`standard_circuit.circuit.{opened,closed,degraded,fallback_invoked,registered}`) with built-in Logger, Sentry, and Sentry::Metrics subscribers
 - ActiveStorage S3 adapter with per-bucket circuit keying
 - Generic ActionMailer delivery-method wrapper (supports both instance and symbol `underlying:` forms)
 - Controller concern for standardized 503 responses on `Stoplight::Error::RedLight`
@@ -19,6 +19,22 @@ Wraps the upstream `stoplight` gem with:
 gem "standard_circuit", git: "https://github.com/rarebit-one/standard_circuit", ref: "<sha>"
 ```
 
+Then run the install generator to drop a commented-out initializer into
+`config/initializers/standard_circuit.rb`:
+
+```bash
+bundle add standard_circuit
+rails g standard_circuit:install
+```
+
+Pass `--with-health-endpoint` to also generate
+`config/initializers/standard_circuit_health.rb` (which requires the opt-in
+health controller); the generator prints the matching route line for you to
+add to `config/routes.rb`.
+
+The generator is idempotent — re-running skips an existing initializer
+unless you pass `--force`.
+
 ## Quick start
 
 ```ruby
@@ -30,7 +46,7 @@ StandardCircuit.configure do |c|
   c.register(:stripe,
     threshold: 5,
     cool_off_time: 30,
-    tracked_errors: StandardCircuit::NetworkErrors.defaults + StandardCircuit::AdapterErrors::Stripe.server_errors,
+    tracked_errors: StandardCircuit::ErrorTaxonomies::Stripe.tracked,
     skipped_errors: StandardCircuit::AdapterErrors::Stripe.caller_errors)
 end
 ```
@@ -42,6 +58,120 @@ StandardCircuit.run(:stripe) do
 end
 ```
 
+## Circuit state storage (`data_store`)
+
+Circuit state (failure counts, colors, locks) lives in a Stoplight data store. StandardCircuit defaults to `Stoplight::DataStore::Memory.new`, which is **per-process**: each Puma worker, Sidekiq/SolidQueue worker, and console gets its own independent view of every circuit.
+
+That is the deliberate default for a Redis-free deployment, and it is usually the right one — a circuit exists to stop *this* process from hammering a dead upstream, and per-process thresholds mean one unlucky worker can't trip the breaker for everyone. But be explicit about what it implies:
+
+- Thresholds are counted per process, so an app with 4 web workers tolerates roughly 4× the configured `threshold` in aggregate before every worker has tripped.
+- `/health` reports the circuit colors of **the process that served the request**, so two consecutive probes can legitimately disagree while a circuit is tripping.
+- `force_open` / `force_closed` and `reset!` affect only the calling process — they are test and console tools, not an operational kill switch.
+
+Point `data_store` at a shared store if you want cross-process state instead:
+
+```ruby
+StandardCircuit.configure do |c|
+  # Default — per-process, no external dependency.
+  c.data_store = Stoplight::DataStore::Memory.new
+
+  # Shared across processes and hosts (requires the redis gem + a Redis server).
+  # c.data_store = Stoplight::DataStore::Redis.new(Redis.new(url: ENV["REDIS_URL"]))
+end
+```
+
+## Sentry reporting
+
+The built-in Sentry subscriber is on by default (`c.sentry_enabled = true`) and reports every circuit-open transition at a flat `:warning`, with the circuit name, colors, and error in `extra`.
+
+Set `sentry_criticality_levels` to derive the level from the circuit's registered `criticality` instead. That also adds `circuit` / `circuit_criticality` tags and a stable `["circuit-open", <circuit>]` fingerprint, so Sentry alert rules can route on criticality (e.g. page on `circuit_criticality:critical`) and group per circuit:
+
+```ruby
+StandardCircuit.configure do |c|
+  # { critical: :error, standard: :warning, optional: :info }
+  c.sentry_criticality_levels = true
+
+  # Or override part of that map — unlisted criticalities keep the default.
+  # c.sentry_criticality_levels = { optional: :debug }
+end
+```
+
+This is **opt-in, not the default**. Both the level and the fingerprint feed Sentry's alerting and issue grouping, so turning it on for existing apps at gem-upgrade time would silently change what pages and re-group open issues. Leaving `sentry_criticality_levels` unset keeps the flat `:warning` shape byte-for-byte.
+
+If you want something else entirely, set `c.sentry_enabled = false` and subscribe to `standard_circuit.circuit.opened` yourself — the payload carries `criticality`.
+
+## Events
+
+Every circuit lifecycle moment is emitted as a Rails event. On Rails 8.1+ the canonical bus is `Rails.event`; on older Rails versions the gem transparently falls back to `ActiveSupport::Notifications`. Detection happens per-emit, so subscribers do not need to care which backend is live.
+
+| Event | When it fires | Payload |
+|-------|---------------|---------|
+| `standard_circuit.circuit.opened` | RED transition (circuit tripped) | `circuit:, from_color:, to_color:, criticality:, error_class:, error_message:` |
+| `standard_circuit.circuit.closed` | GREEN transition (recovered) | `circuit:, from_color:, to_color:, criticality:` |
+| `standard_circuit.circuit.degraded` | YELLOW transition (half-open probe) | `circuit:, from_color:, to_color:, criticality:` |
+| `standard_circuit.circuit.fallback_invoked` | Runner returned a fallback instead of raising RedLight | `circuit:, reason: (:circuit_open\|:forced_open), criticality:` |
+| `standard_circuit.circuit.registered` | `Config#register` / `register_prefix` was called (see note below) | `circuit:, criticality:, scope: (:name\|:prefix)` |
+| `standard_circuit.run.completed` | Every wrapped `StandardCircuit.run` call (success, failure, or circuit_open) | `circuit:, status: (:success\|:failure\|:circuit_open), duration_ms:, criticality:, error_class:, error_message:` |
+
+> **Note on `standard_circuit.run.completed`:** the per-call event for cost / latency / success-rate dashboards. Fires on every `Runner#execute` invocation and on `force_open` runs; **not** emitted for `force_closed` runs (which intentionally bypass the runner). All payload keys are always present — `error_class` and `error_message` are `nil` on `:success`. Payload duration uses `duration_ms` (numeric), not `event.duration`, so subscribers work identically on the `Rails.event` and `ActiveSupport::Notifications` backends.
+
+> **Note on `standard_circuit.circuit.registered`:** subscribers are wired up *after* the `StandardCircuit.configure` block yields, so any `c.register` calls inside that block fire before any subscriber can hear them. This event is reliable only for post-boot, dynamic `register` / `register_prefix` calls — do not rely on it for a boot-time circuit inventory.
+
+Built-in subscribers (Logger / Sentry / Metrics) are registered automatically by the gem's Railtie. Host apps can subscribe to the namespace however they like:
+
+```ruby
+# Rails 8.1+
+class MyAuditSubscriber
+  def emit(event)
+    return unless event[:name].start_with?("standard_circuit.")
+    Rails.logger.info("circuit event: #{event[:name]} #{event[:payload].inspect}")
+  end
+end
+Rails.event.subscribe(MyAuditSubscriber.new)
+
+# Older Rails
+ActiveSupport::Notifications.subscribe(/\Astandard_circuit\./) do |name, _start, _finish, _id, payload|
+  Rails.logger.info("circuit event: #{name} #{payload.inspect}")
+end
+
+# Quick host-supplied callable (auto-wired at boot via the Railtie)
+StandardCircuit.configure do |c|
+  c.add_notifier(->(name, payload) { MyAlerting.notify(name, payload) })
+end
+```
+
+## Streaming and non-controller contexts
+
+`ControllerSupport.circuit_open_fallback` only works for non-streaming responses — once a `Live` controller has flushed any output, Rails can't render an error template over the wire. For a streaming controller, catch `Stoplight::Error::RedLight` *inside* the streaming proc and write a degraded payload before the stream closes:
+
+```ruby
+class Api::MessagesController < ApplicationController
+  include ActionController::Live
+
+  def stream
+    response.headers["Content-Type"] = "application/x-ndjson"
+
+    StandardCircuit.run(:openai) do
+      llm.stream do |chunk|
+        response.stream.write({ delta: chunk }.to_json + "\n")
+      end
+    end
+  rescue Stoplight::Error::RedLight
+    # Only reachable when the circuit was already open at call time —
+    # Stoplight raises RedLight before executing the block, not mid-stream.
+    # Errors raised mid-stream propagate as their original class through the
+    # `ensure` below; add a broader rescue if you also need to write a
+    # terminal NDJSON line for those.
+    response.stream.write({ error: "service_unavailable" }.to_json + "\n")
+  ensure
+    response.stream.close
+  end
+end
+```
+
+Same pattern applies in background jobs (where `circuit_open_fallback` doesn't help): wrap the work in `StandardCircuit.run` and rescue `Stoplight::Error::RedLight` to either `discard_on` (avoid thundering retries) or `retry_on` with backoff (defer until cool-off), depending on whether eventual delivery is required.
+
+
 ## Health endpoint
 
 StandardCircuit ships an opt-in controller that renders `StandardCircuit.health_report` as JSON. It returns 503 when the rolled-up status is `:critical` (so orchestrators pull the instance out of rotation) and 200 otherwise.
@@ -59,7 +189,14 @@ end
 
 The controller inherits from `ActionController::API` to sidestep app-level filters (authentication, bootstrap redirects, etc.) so probes can call it anonymously.
 
-See [`standard_circuit-design.md`](../standard_circuit-design.md) for the full design.
+**If your app also mounts `StandardHealth::Engine` at `/health`, draw the aggregate route first:**
+
+```ruby
+get "/health", to: "standard_circuit/health#show"        # aggregate — FIRST
+mount StandardHealth::Engine => "/health", as: :standard_health
+```
+
+`StandardHealth::Engine` registers sub-paths only (`/alive`, `/ready`, `/diagnostics/env`) — it never serves the aggregate tier itself. An app that mounts the engine and assumes `/health` is covered silently has no aggregate tier at all, with no boot error and no failing route spec to reveal it. The ordering is load-bearing; draw the aggregate route explicitly, first.
 
 ## License
 

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

@@ -0,0 +1,83 @@
+require "rails/generators"
+
+module StandardCircuit
+  module Generators
+    # Installs StandardCircuit in a host Rails application.
+    #
+    # By default, writes config/initializers/standard_circuit.rb with
+    # commented-out examples covering the public Config DSL.
+    #
+    # When +--with-health-endpoint+ is passed, also writes
+    # config/initializers/standard_circuit_health.rb (which requires the
+    # opt-in HealthController) and prints the route line the host should
+    # add to config/routes.rb to expose the endpoint.
+    #
+    # Idempotent: re-running on an existing initializer logs and skips. Pass
+    # +--force+ to overwrite.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DESC
+        Installs StandardCircuit. By default this writes
+        config/initializers/standard_circuit.rb with commented-out examples
+        covering circuit registration, prefix registration, and notifier
+        wiring.
+
+        Pass --with-health-endpoint to also write
+        config/initializers/standard_circuit_health.rb (which requires the
+        opt-in HealthController) and print the route line to add to
+        config/routes.rb.
+
+        The generator is idempotent — already-installed initializers are
+        skipped with a clear message. Pass --force to overwrite.
+      DESC
+
+      class_option :with_health_endpoint, type: :boolean, default: false,
+        desc: "Also create config/initializers/standard_circuit_health.rb and print the route hint"
+
+      def create_initializer_file
+        path = "config/initializers/standard_circuit.rb"
+        if File.exist?(File.join(destination_root, path)) && !options[:force]
+          say_status("skip", "#{path} already present, skipping (use --force to overwrite)", :yellow)
+          return
+        end
+
+        template "initializer.rb.tt", path
+      end
+
+      def create_health_initializer_file
+        return unless options[:with_health_endpoint]
+
+        path = "config/initializers/standard_circuit_health.rb"
+        if File.exist?(File.join(destination_root, path)) && !options[:force]
+          say_status("skip", "#{path} already present, skipping (use --force to overwrite)", :yellow)
+        else
+          template "health_initializer.rb.tt", path
+        end
+      end
+
+      def print_health_route_hint
+        return unless options[:with_health_endpoint]
+
+        say ""
+        say "=" * 79
+        say "StandardCircuit health endpoint installed."
+        say ""
+        say "Add the following to config/routes.rb to expose the endpoint:"
+        say ""
+        say '  get "/health", to: "standard_circuit/health#show"'
+        say ""
+        say "If you also mount StandardHealth::Engine at \"/health\", draw the"
+        say "line above BEFORE the mount. That engine serves sub-paths only"
+        say "(/alive, /ready, /diagnostics/env), never the aggregate tier — so"
+        say "an app that mounts it and assumes \"/health\" is covered silently has"
+        say "no aggregate tier, with no boot error to warn you."
+        say ""
+        say "The controller returns 503 when the rolled-up circuit health is"
+        say ":critical and 200 otherwise — wire it up to your load balancer."
+        say "=" * 79
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/standard_circuit/install/templates/health_initializer.rb.tt

@@ -0,0 +1,25 @@
+# StandardCircuit health-check controller
+# Generated by: rails g standard_circuit:install --with-health-endpoint
+#
+# The controller is opt-in: this require pulls it onto the autoload path so
+# the route below resolves. Add the matching route to config/routes.rb:
+#
+#   get "/health", to: "standard_circuit/health#show"
+#
+# ORDERING IS LOAD-BEARING: if your app also mounts StandardHealth::Engine at
+# "/health", draw this aggregate route BEFORE the mount —
+#
+#   get "/health", to: "standard_circuit/health#show"        # aggregate — FIRST
+#   mount StandardHealth::Engine => "/health", as: :standard_health
+#
+# StandardHealth::Engine registers sub-paths only ("/alive", "/ready",
+# "/diagnostics/env") — it never serves the aggregate tier itself. So an app
+# that mounts the engine and assumes "/health" is covered has no aggregate tier
+# at all, and nothing says so: no boot error, and no failing route spec unless
+# one already exists. Draw this route explicitly, first.
+#
+# The endpoint renders StandardCircuit.health_report as JSON and returns
+# 503 when the rolled-up status is :critical (so orchestrators pull the
+# instance out of rotation) and 200 otherwise.
+
+require "standard_circuit/health_controller"

data/lib/generators/standard_circuit/install/templates/initializer.rb.tt

@@ -0,0 +1,104 @@
+# StandardCircuit configuration
+# Generated by: rails g standard_circuit:install
+#
+# StandardCircuit wraps the upstream `stoplight` gem with an opinionated
+# error taxonomy, Sentry/metrics notifiers, ActiveStorage and ActionMailer
+# adapters, and a Rails-aware health rollup.
+#
+# All commented-out lines below show the public DSL — uncomment and edit
+# the ones that apply to your app.
+
+StandardCircuit.configure do |config|
+  # ---------------------------------------------------------------------------
+  # Global settings
+  # ---------------------------------------------------------------------------
+
+  # Send Sentry warnings on GREEN -> RED transitions.
+  # Default: true
+  # config.sentry_enabled = true
+
+  # Report circuit-open events at a Sentry level chosen from the circuit's
+  # criticality, and add `circuit` / `circuit_criticality` tags plus a stable
+  # ["circuit-open", <circuit>] fingerprint so Sentry alert rules can route and
+  # group by circuit. Opt-in: leaving this unset keeps the flat :warning
+  # reporting (no tags, no fingerprint) that earlier versions used.
+  #   true  -> { critical: :error, standard: :warning, optional: :info }
+  #   Hash  -> the above, merged with your overrides
+  # Default: nil (flat :warning)
+  # config.sentry_criticality_levels = true
+  # config.sentry_criticality_levels = { optional: :debug }
+
+  # Prefix used for emitted metrics (e.g. "<prefix>.circuit_breaker",
+  # "<prefix>.request"). Default: "external"
+  # config.metric_prefix = "external"
+
+  # Logger used by the built-in Logger notifier. Falls back to nil (no
+  # logging) when unset; assign Rails.logger or a custom logger to enable.
+  # Default: nil
+  # config.logger = Rails.logger
+
+  # Stoplight data store. Default: in-memory (per-process). Use a shared
+  # store (e.g. Stoplight::DataStore::Redis) when you want circuit state
+  # shared across processes/hosts.
+  # Default: Stoplight::DataStore::Memory.new
+  # config.data_store = Stoplight::DataStore::Redis.new(Redis.new)
+
+  # ---------------------------------------------------------------------------
+  # Circuit registration
+  # ---------------------------------------------------------------------------
+  # Each call to `register` declares a named circuit. Supported options:
+  #
+  #   threshold       — failures before tripping (default: 3)
+  #   cool_off_time   — seconds before half-open retry (default: 30)
+  #   window_size     — seconds for the rolling failure window (default: 60)
+  #   tracked_errors  — error classes that count toward the threshold
+  #                     (default: StandardCircuit::NetworkErrors.defaults)
+  #   skipped_errors  — error classes that bypass the circuit (re-raised
+  #                     without counting — typically caller/validation errors)
+  #   criticality     — :critical | :standard | :optional
+  #                     (affects health rollup; default: :standard)
+
+  # config.register(:stripe,
+  #   threshold: 5,
+  #   cool_off_time: 60,
+  #   tracked_errors: StandardCircuit::ErrorTaxonomies::Stripe.tracked,
+  #   skipped_errors: StandardCircuit::AdapterErrors::Stripe.caller_errors,
+  #   criticality: :critical)
+
+  # config.register(:smtp,
+  #   tracked_errors: StandardCircuit::ErrorTaxonomies::Smtp.tracked,
+  #   criticality: :standard)
+
+  # ---------------------------------------------------------------------------
+  # Prefix registration
+  # ---------------------------------------------------------------------------
+  # Use `register_prefix` to dynamically name circuits matching a pattern.
+  # The first matching prefix wins; the circuit name is "<prefix>_<suffix>".
+
+  # config.register_prefix(:s3,
+  #   threshold: 10,
+  #   tracked_errors: StandardCircuit::ErrorTaxonomies::Aws.tracked,
+  #   criticality: :standard)
+
+  # ---------------------------------------------------------------------------
+  # Extra notifiers
+  # ---------------------------------------------------------------------------
+  # Built-in subscribers (Logger / Sentry / Metrics) are wired up automatically.
+  # For most cases, prefer subscribing to the `standard_circuit.*` namespace
+  # directly via `Rails.event.subscribe` (Rails 8.1+) or
+  # `ActiveSupport::Notifications.subscribe`. `add_notifier` is a convenience
+  # for registering a callable that follows the same `call(event_name, payload)`
+  # contract as the built-in subscribers.
+
+  # config.add_notifier(->(name, payload) { MyTracer.record(name, payload) })
+
+  # ---------------------------------------------------------------------------
+  # Health endpoint (see --with-health-endpoint)
+  # ---------------------------------------------------------------------------
+  # The aggregate route is `get "/health", to: "standard_circuit/health#show"`.
+  # If your app also mounts StandardHealth::Engine at "/health", draw the
+  # aggregate route BEFORE the mount. That engine registers sub-paths only
+  # ("/alive", "/ready", "/diagnostics/env") and never serves the aggregate tier
+  # itself, so an app that mounts it and assumes "/health" is covered silently
+  # has no aggregate tier — no boot error, no failing route spec.
+end

data/lib/standard_circuit/config.rb

@@ -34,10 +34,11 @@ module StandardCircuit
     end
 
     attr_accessor :sentry_enabled, :metric_prefix, :data_store, :logger
-    attr_reader :circuits, :prefixes, :extra_notifiers
+    attr_reader :circuits, :prefixes, :extra_notifiers, :sentry_criticality_levels
 
     def initialize
       @sentry_enabled = true
+      @sentry_criticality_levels = nil
       @metric_prefix = "external"
       @data_store = Stoplight::DataStore::Memory.new
       @logger = nil
@@ -46,11 +47,20 @@ module StandardCircuit
       @extra_notifiers = []
     end
 
-    def notifiers
-      built = [ Notifiers::Logger.new(@logger) ]
-      built << Notifiers::Sentry.new if @sentry_enabled
-      built << Notifiers::Metrics.new(metric_prefix: @metric_prefix)
-      built + @extra_notifiers
+    # Opt in to criticality-aware Sentry reporting for the built-in Sentry
+    # subscriber. Accepts:
+    #
+    #   nil / false  — (default) flat :warning for every circuit, no tags and
+    #                  no fingerprint. The 0.2.x behaviour.
+    #   true         — Notifiers::Sentry::DEFAULT_LEVELS
+    #                  ({ critical: :error, standard: :warning, optional: :info })
+    #   Hash         — DEFAULT_LEVELS merged with the given criticality => level
+    #                  pairs, so a partial map is enough.
+    #
+    # Stored normalized: the reader returns either nil or a frozen, complete
+    # criticality => level Hash.
+    def sentry_criticality_levels=(value)
+      @sentry_criticality_levels = normalize_sentry_criticality_levels(value)
     end
 
     def reset_registry!
@@ -60,14 +70,34 @@ module StandardCircuit
     end
 
     def register(name, **opts)
-      @circuits[name.to_sym] = CircuitSpec.build(**opts)
+      spec = CircuitSpec.build(**opts)
+      @circuits[name.to_sym] = spec
+      EventEmitter.emit("standard_circuit.circuit.registered",
+        circuit: name.to_s,
+        criticality: spec.criticality,
+        scope: :name)
+      spec
     end
 
     def register_prefix(prefix, **opts)
-      @prefixes[prefix.to_s] = CircuitSpec.build(**opts)
+      spec = CircuitSpec.build(**opts)
+      @prefixes[prefix.to_s] = spec
+      EventEmitter.emit("standard_circuit.circuit.registered",
+        circuit: prefix.to_s,
+        criticality: spec.criticality,
+        scope: :prefix)
+      spec
     end
 
+    # Register a host-supplied subscriber. Subscribers must respond to
+    # `call(event_name, payload)` — Stoplight-shaped 4-arg notifiers from the
+    # 0.1.x API are no longer accepted as extras (Logger / Sentry / Metrics
+    # demonstrate the new shape).
     def add_notifier(notifier)
+      unless notifier.respond_to?(:call)
+        raise ArgumentError,
+          "extra notifiers must respond to `call(event_name, payload)`; got #{notifier.class}"
+      end
       @extra_notifiers << notifier
     end
 
@@ -77,6 +107,39 @@ module StandardCircuit
 
     private
 
+    def normalize_sentry_criticality_levels(value)
+      case value
+      when nil, false then nil
+      when true       then Notifiers::Sentry::DEFAULT_LEVELS
+      when Hash       then merge_sentry_criticality_levels(value)
+      else
+        raise ArgumentError,
+          "sentry_criticality_levels must be nil, true, false, or a Hash of " \
+          "criticality => Sentry level; got #{value.class}"
+      end
+    end
+
+    def merge_sentry_criticality_levels(map)
+      normalized = map.to_h do |criticality, level|
+        # Check symbolizability before coercing: a key like 42 would otherwise
+        # raise NoMethodError instead of the ArgumentError this setter promises.
+        criticality = criticality.to_sym if criticality.respond_to?(:to_sym)
+        unless CRITICALITIES.include?(criticality)
+          raise ArgumentError,
+            "invalid criticality #{criticality.inspect} in sentry_criticality_levels; " \
+            "must be one of #{CRITICALITIES.inspect}"
+        end
+        unless level.respond_to?(:to_sym)
+          raise ArgumentError,
+            "invalid Sentry level #{level.inspect} for criticality #{criticality.inspect}; " \
+            "must be a Symbol or String"
+        end
+        [ criticality, level.to_sym ]
+      end
+
+      Notifiers::Sentry::DEFAULT_LEVELS.merge(normalized).freeze
+    end
+
     def spec_for_prefix(name)
       key = name.to_s
       _matched_prefix, spec = @prefixes.find { |prefix, _| key.start_with?("#{prefix}_") }

data/lib/standard_circuit/engine.rb

@@ -0,0 +1,36 @@
+module StandardCircuit
+  # Boot hook: register the internal Logger / Sentry / Metrics subscribers (and
+  # any `extra_notifiers` the host configured) against whichever event bus is
+  # live in this Rails version.
+  #
+  # We hook `after: :load_config_initializers` so any host-side
+  # `StandardCircuit.configure` block in `config/initializers/*` has finished
+  # running and `extra_notifiers` / `metric_prefix` / `logger` are in their
+  # final state when the subscriber set is built. This is independent of
+  # ActiveRecord — apps that don't load AR still need observability.
+  class Engine < ::Rails::Engine
+    # Brings StandardCircuit in line with the other engine gems in the family.
+    # Safe here specifically because this engine is library-only:
+    #
+    # * No `config/routes.rb`, so the `default_scope` isolate_namespace applies
+    #   to the engine's own route set has nothing to scope.
+    # * No ActiveRecord models, so the `standard_circuit_` table_name_prefix it
+    #   defines on the StandardCircuit module applies to nothing.
+    # * The host-drawn route the convention prescribes —
+    #   `get "/health", to: "standard_circuit/health#show"` — resolves through
+    #   the *application's* route set by constant lookup, which isolation does
+    #   not touch. Verified by booting a real Rails app both ways (see
+    #   spec/integration/health_route_boot_spec.rb, which fails if this ever
+    #   regresses).
+    #
+    # One real consequence: `StandardCircuit::HealthController` now picks up the
+    # engine's (empty) url_helpers instead of the application's, so app path
+    # helpers inside it — or inside a host subclass of it — need a `main_app.`
+    # prefix. The controller only renders JSON, so nothing in-gem is affected.
+    isolate_namespace StandardCircuit
+
+    initializer "standard_circuit.subscribers", after: :load_config_initializers do
+      StandardCircuit.subscribers.setup!
+    end
+  end
+end

data/lib/standard_circuit/event_emitter.rb

@@ -0,0 +1,35 @@
+module StandardCircuit
+  # Internal helper that emits StandardCircuit lifecycle events through whichever
+  # event reporter is live in the host process.
+  #
+  # - On Rails 8.1+, `Rails.event.notify(name, **payload)` is the canonical bus.
+  # - On older Rails (or any host without the structured reporter), we fall back
+  #   to `ActiveSupport::Notifications.instrument(name, payload)`.
+  #
+  # Detection is performed at *call time* — the gem is required before Rails has
+  # finished booting, so we cannot cache the decision at load time.
+  #
+  # @api private
+  module EventEmitter
+    module_function
+
+    # Emit a single event. Both backends are best-effort: any exception raised
+    # by a subscriber is swallowed so circuit-breaker observability never takes
+    # down a circuit-protected request.
+    def emit(event_name, payload)
+      if rails_event_available?
+        ::Rails.event.notify(event_name, **payload)
+      else
+        ::ActiveSupport::Notifications.instrument(event_name, payload)
+      end
+    rescue => e
+      warn "[StandardCircuit] event emit for #{event_name.inspect} failed: #{e.class}: #{e.message}"
+    end
+
+    def rails_event_available?
+      defined?(::Rails) &&
+        ::Rails.respond_to?(:event) &&
+        ::Rails.event.respond_to?(:notify)
+    end
+  end
+end

data/lib/standard_circuit/notifier_bridge.rb

@@ -0,0 +1,49 @@
+module StandardCircuit
+  # Stoplight-shaped notifier whose only job is to translate the upstream
+  # `notifier.notify(light, from_color, to_color, error)` callback into a
+  # StandardCircuit Rails event.
+  #
+  # Stoplight calls notifiers on every color transition (GREEN<->RED, RED->YELLOW
+  # for half-open recovery). We map each transition to a stable event name and
+  # forward a uniform payload to whichever event bus is live.
+  #
+  # This is the single Stoplight notifier StandardCircuit registers — Logger,
+  # Sentry, and Metrics are now subscribers, not direct notifiers.
+  #
+  # @api private
+  class NotifierBridge
+    EVENT_FOR_COLOR = {
+      Stoplight::Color::RED    => "standard_circuit.circuit.opened",
+      Stoplight::Color::GREEN  => "standard_circuit.circuit.closed",
+      Stoplight::Color::YELLOW => "standard_circuit.circuit.degraded"
+    }.freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    def notify(light, from_color, to_color, error)
+      event_name = EVENT_FOR_COLOR[to_color]
+      return unless event_name
+
+      EventEmitter.emit(event_name, payload_for(light, from_color, to_color, error))
+    end
+
+    private
+
+    def payload_for(light, from_color, to_color, error)
+      spec = @config.spec_for(light.name)
+      payload = {
+        circuit: light.name,
+        from_color: from_color,
+        to_color: to_color,
+        criticality: spec&.criticality
+      }
+      if error
+        payload[:error_class] = error.class.name
+        payload[:error_message] = error.message
+      end
+      payload
+    end
+  end
+end

data/lib/standard_circuit/notifiers/logger.rb

@@ -2,23 +2,43 @@ require "logger"
 
 module StandardCircuit
   module Notifiers
+    # Subscribes to standard_circuit.circuit.* events and writes a human-readable
+    # log line for each transition. Always-on by default; pass a custom logger
+    # via `StandardCircuit.config.logger=`.
     class Logger
+      TRANSITION_EVENTS = %w[
+        standard_circuit.circuit.opened
+        standard_circuit.circuit.closed
+        standard_circuit.circuit.degraded
+      ].freeze
+
       def initialize(logger = nil)
         @logger = logger || ::Logger.new($stdout)
       end
 
-      def notify(light, from_color, to_color, error)
-        message = build_message(light, from_color, to_color, error)
-        level = to_color == Stoplight::Color::RED ? :warn : :info
+      def call(event_name, payload)
+        return unless TRANSITION_EVENTS.include?(event_name)
+
+        message = build_message(event_name, payload)
+        level = event_name == "standard_circuit.circuit.opened" ? :warn : :info
         @logger.public_send(level, message)
         message
       end
 
       private
 
-      def build_message(light, from_color, to_color, error)
-        words = [ "Stoplight", light.name, "switched from", from_color, "to", to_color ]
-        words += [ "because", error.class.name, error.message ] if error
+      def build_message(event_name, payload)
+        words = [
+          "Stoplight",
+          payload[:circuit],
+          "switched from",
+          payload[:from_color],
+          "to",
+          payload[:to_color]
+        ]
+        if payload[:error_class]
+          words += [ "because", payload[:error_class], payload[:error_message] ]
+        end
         words.join(" ")
       end
     end

data/lib/standard_circuit/notifiers/metrics.rb

@@ -1,22 +1,26 @@
 module StandardCircuit
   module Notifiers
+    # Subscribes to all standard_circuit.circuit.{opened,closed,degraded} events
+    # and emits a Sentry::Metrics counter with the canonical state name.
     class Metrics
-      STATE_FOR_COLOR = {
-        Stoplight::Color::RED => "opened",
-        Stoplight::Color::GREEN => "closed",
-        Stoplight::Color::YELLOW => "half_open"
+      STATE_FOR_EVENT = {
+        "standard_circuit.circuit.opened"   => "opened",
+        "standard_circuit.circuit.closed"   => "closed",
+        "standard_circuit.circuit.degraded" => "half_open"
       }.freeze
 
       def initialize(metric_prefix: "external")
         @metric_prefix = metric_prefix
       end
 
-      def notify(light, _from_color, to_color, _error)
-        state = STATE_FOR_COLOR.fetch(to_color, to_color)
+      def call(event_name, payload)
+        state = STATE_FOR_EVENT[event_name]
+        return unless state
+
         ::Sentry::Metrics.count(
           "#{@metric_prefix}.circuit_breaker",
           value: 1,
-          attributes: { service: light.name, state: state }
+          attributes: { service: payload[:circuit], state: state }
         )
       end
     end

data/lib/standard_circuit/notifiers/sentry.rb

@@ -1,24 +1,88 @@
 module StandardCircuit
   module Notifiers
+    # Subscribes to standard_circuit.circuit.opened and forwards a message to
+    # Sentry. Other transitions are ignored — only RED matters for alerting.
+    #
+    # Two reporting shapes:
+    #
+    # * **Flat** (default, and the only 0.2.x behaviour): every circuit reports
+    #   at `:warning` with the circuit's colors and error in `extra`. No tags,
+    #   no fingerprint.
+    # * **Criticality-aware** (opt in via `config.sentry_criticality_levels`):
+    #   the level is chosen from the circuit's registered criticality, and the
+    #   report gains `circuit` / `circuit_criticality` tags plus a stable
+    #   `["circuit-open", circuit]` fingerprint so Sentry alert rules can route
+    #   and group by circuit.
+    #
+    # Flat stays the default deliberately. Both the level and the fingerprint
+    # feed Sentry's alerting and grouping, so a gem bump must not silently
+    # re-page or re-group a host app's existing issues — see CHANGELOG.
     class Sentry
-      def notify(light, from_color, to_color, error)
-        return unless to_color == Stoplight::Color::RED
+      OPENED_EVENT = "standard_circuit.circuit.opened".freeze
+
+      # Level used in flat mode, and the fallback for an unrecognised
+      # criticality in criticality-aware mode.
+      DEFAULT_LEVEL = :warning
+
+      # The recommended criticality -> Sentry level mapping, used when
+      # `config.sentry_criticality_levels = true`. :critical is loud enough to
+      # page; :optional stays informational so a flapping nice-to-have
+      # upstream doesn't cry wolf.
+      DEFAULT_LEVELS = {
+        critical: :error,
+        standard: :warning,
+        optional: :info
+      }.freeze
+
+      # @param levels [Hash{Symbol=>Symbol}, nil] criticality -> level map.
+      #   nil (the default) selects flat :warning reporting.
+      def initialize(levels: nil)
+        @levels = levels
+      end
+
+      def call(event_name, payload)
+        return unless event_name == OPENED_EVENT
         return unless defined?(::Sentry) && ::Sentry.respond_to?(:capture_message)
 
-        message = "Circuit breaker opened: #{light.name}"
+        @levels ? capture_criticality_aware(payload) : capture_flat(payload)
+      end
+
+      private
+
+      def capture_flat(payload)
+        message = "Circuit breaker opened: #{payload[:circuit]}"
         ::Sentry.capture_message(
           message,
-          level: :warning,
-          extra: {
-            circuit: light.name,
-            from_color: from_color,
-            to_color: to_color,
-            error_class: error&.class&.name,
-            error_message: error&.message
-          }.compact
+          level: DEFAULT_LEVEL,
+          extra: base_extra(payload)
         )
         message
       end
+
+      def capture_criticality_aware(payload)
+        circuit = payload[:circuit].to_s
+        criticality = (payload[:criticality] || Config::DEFAULT_CRITICALITY).to_sym
+        message = "Circuit breaker opened: #{circuit} (#{criticality})"
+
+        ::Sentry.capture_message(
+          message,
+          level: @levels.fetch(criticality, DEFAULT_LEVEL),
+          tags: { circuit: circuit, circuit_criticality: criticality.to_s },
+          fingerprint: [ "circuit-open", circuit ],
+          extra: base_extra(payload).merge(circuit: circuit, criticality: criticality)
+        )
+        message
+      end
+
+      def base_extra(payload)
+        {
+          circuit: payload[:circuit],
+          from_color: payload[:from_color],
+          to_color: payload[:to_color],
+          error_class: payload[:error_class],
+          error_message: payload[:error_message]
+        }.compact
+      end
     end
   end
 end

data/lib/standard_circuit/rspec.rb

@@ -5,14 +5,27 @@ require "standard_circuit"
 # - Clears the light cache so rebuilt lights pick up fresh config if a spec
 #   mutates it.
 # - Clears forced states (force_open / force_closed).
+# - Tears down all event subscribers so a spec that subscribes manually doesn't
+#   leak listeners into the next example. The internal Logger/Sentry/Metrics
+#   subscribers are re-registered if a spec calls `StandardCircuit.configure`
+#   or `StandardCircuit.subscribers.setup!`.
 # - Swaps a fresh Stoplight::DataStore::Memory into the Config when the
 #   current store is already Memory, so failure counters from one spec don't
 #   leak into the next. Redis stores are left alone.
 #
+# Circuit registrations are intentionally NOT cleared. Host apps usually
+# define circuits once in a `config/initializers/standard_circuit.rb`
+# initializer; clearing the registry between examples would force every spec
+# to re-`configure`. Specs that register circuits in `before(:each)` are
+# unaffected by leftover registrations from prior examples (the new register
+# call wins). If you do need a clean registry, call
+# `StandardCircuit.config.reset_registry!` explicitly in your own hook.
+#
 # This is intentionally `before(:each)` rather than `after(:each)` so the
 # setup happens even when a previous example aborted in an after hook.
 RSpec.configure do |config|
   config.before(:each) do
     StandardCircuit.reset!
+    StandardCircuit.subscribers.teardown!
   end
 end

data/lib/standard_circuit/runner.rb

@@ -86,21 +86,32 @@ module StandardCircuit
       light = light_for(name)
 
       result = fallback ? light.run(fallback, &block) : light.run(&block)
-      emit_request_metric(name, :success, duration_ms(started_at))
+      duration = duration_ms(started_at)
+      emit_request_metric(name, :success, duration)
+      emit_run_completed(name, status: :success, duration_ms: duration)
       result
     rescue Stoplight::Error::RedLight => e
-      emit_request_metric(name, :circuit_open, duration_ms(started_at))
+      duration = duration_ms(started_at)
+      emit_request_metric(name, :circuit_open, duration)
+      emit_run_completed(name, status: :circuit_open, duration_ms: duration, error: e)
       raise e unless fallback
 
+      emit_fallback_invoked(name, reason: :circuit_open)
       fallback.call(nil)
     rescue StandardError => e
-      emit_request_metric(name, :failure, duration_ms(started_at))
+      duration = duration_ms(started_at)
+      emit_request_metric(name, :failure, duration)
+      emit_run_completed(name, status: :failure, duration_ms: duration, error: e)
       raise e
     end
 
     def run_forced_open(name, fallback)
       emit_request_metric(name, :circuit_open, 0)
-      return fallback.call(nil) if fallback
+      emit_run_completed(name, status: :circuit_open, duration_ms: 0)
+      if fallback
+        emit_fallback_invoked(name, reason: :forced_open)
+        return fallback.call(nil)
+      end
 
       spec = @config.spec_for(name)
       raise Stoplight::Error::RedLight.new(
@@ -138,14 +149,10 @@ module StandardCircuit
         tracked_errors: spec.tracked_errors,
         skipped_errors: spec.skipped_errors,
         data_store: @config.data_store,
-        notifiers: notifiers
+        notifiers: [ NotifierBridge.new(@config) ]
       )
     end
 
-    def notifiers
-      @config.notifiers
-    end
-
     def emit_request_metric(name, status, duration)
       prefix = @config.metric_prefix
       attrs = { service: name.to_s, status: status.to_s }
@@ -153,6 +160,25 @@ module StandardCircuit
       ::Sentry::Metrics.distribution("#{prefix}.request.duration", duration, unit: "millisecond", attributes: attrs)
     end
 
+    def emit_fallback_invoked(name, reason:)
+      spec = @config.spec_for(name)
+      EventEmitter.emit("standard_circuit.circuit.fallback_invoked",
+        circuit: name.to_s,
+        reason: reason,
+        criticality: spec&.criticality)
+    end
+
+    def emit_run_completed(name, status:, duration_ms:, error: nil)
+      spec = @config.spec_for(name)
+      EventEmitter.emit("standard_circuit.run.completed",
+        circuit: name.to_s,
+        status: status,
+        duration_ms: duration_ms,
+        criticality: spec&.criticality,
+        error_class: error&.class&.name,
+        error_message: error&.message)
+    end
+
     def monotonic_now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

data/lib/standard_circuit/subscribers.rb

@@ -0,0 +1,102 @@
+module StandardCircuit
+  # Registers internal and user-supplied subscribers against whichever event
+  # bus is live (Rails.event on 8.1+, ActiveSupport::Notifications elsewhere).
+  #
+  # Each subscriber must respond to `call(event_name, payload)`. Internal
+  # subscribers (Logger / Sentry / Metrics) are built from the live config so
+  # changes to `metric_prefix` / `logger` propagate when `setup!` is re-run.
+  #
+  # Subscriptions cover the namespace prefix `standard_circuit.`, so a single
+  # registration on each backend listens for every lifecycle event the gem
+  # emits — bridge color transitions plus runner-side fallback / registration.
+  #
+  # @api private
+  class Subscribers
+    EVENT_PATTERN = "standard_circuit."
+    EVENT_REGEXP = /\A#{Regexp.escape(EVENT_PATTERN)}/
+
+    def initialize
+      @rails_event_subscribers = []
+      @as_subscribers = []
+    end
+
+    def setup!
+      teardown!
+      register(internal_subscribers + extra_subscribers)
+    end
+
+    # Tear down both backends. Rails.event subscribers are unsubscribed
+    # unconditionally — we recorded them at registration time, so we must
+    # remove them even if Rails.event has since become unavailable (e.g. test
+    # `hide_const("Rails")`). Otherwise the wrappers would remain live in the
+    # bus while we believe they are gone.
+    def teardown!
+      @rails_event_subscribers.each do |subscriber|
+        ::Rails.event.unsubscribe(subscriber) if EventEmitter.rails_event_available?
+      rescue StandardError
+        # If Rails.event is gone (test isolation), we can do nothing more —
+        # clearing the array still releases our reference.
+      end
+      @rails_event_subscribers.clear
+
+      @as_subscribers.each do |subscriber|
+        ::ActiveSupport::Notifications.unsubscribe(subscriber)
+      end
+      @as_subscribers.clear
+    end
+
+    private
+
+    def register(subscribers)
+      subscribers.each do |subscriber|
+        register_one(subscriber)
+      end
+    end
+
+    # Register on whichever backend is live. We do not double-subscribe — if
+    # `Rails.event` is present, every emit goes through it (see EventEmitter),
+    # so the AS::Notifications side would never receive anything.
+    def register_one(subscriber)
+      if EventEmitter.rails_event_available?
+        wrapper = RailsEventAdapter.new(subscriber)
+        ::Rails.event.subscribe(wrapper)
+        @rails_event_subscribers << wrapper
+      else
+        handle = ::ActiveSupport::Notifications.subscribe(EVENT_REGEXP) do |name, _start, _finish, _id, payload|
+          subscriber.call(name, payload)
+        end
+        @as_subscribers << handle
+      end
+    end
+
+    def internal_subscribers
+      config = StandardCircuit.config
+      list = [ Notifiers::Logger.new(config.logger) ]
+      list << Notifiers::Sentry.new(levels: config.sentry_criticality_levels) if config.sentry_enabled
+      list << Notifiers::Metrics.new(metric_prefix: config.metric_prefix)
+      list
+    end
+
+    # Config#add_notifier already enforces that every entry responds to :call,
+    # so we can hand the array straight through to register/1.
+    def extra_subscribers
+      StandardCircuit.config.extra_notifiers
+    end
+
+    # Adapts a `call(name, payload)` subscriber to the Rails.event#subscribe
+    # contract, which delivers a Hash event with :name / :payload / :context /
+    # :tags / :source_location.
+    class RailsEventAdapter
+      def initialize(subscriber)
+        @subscriber = subscriber
+      end
+
+      def emit(event)
+        name = event[:name]
+        return unless name&.start_with?(EVENT_PATTERN)
+
+        @subscriber.call(name, event[:payload] || {})
+      end
+    end
+  end
+end

data/lib/standard_circuit/version.rb

@@ -1,3 +1,3 @@
 module StandardCircuit
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/standard_circuit.rb

@@ -9,15 +9,19 @@ require "standard_circuit/adapter_errors/aws"
 require "standard_circuit/adapter_errors/faraday"
 require "standard_circuit/adapter_errors/smtp"
 require "standard_circuit/error_taxonomies"
+require "standard_circuit/event_emitter"
+require "standard_circuit/notifier_bridge"
 require "standard_circuit/notifiers/logger"
 require "standard_circuit/notifiers/sentry"
 require "standard_circuit/notifiers/metrics"
+require "standard_circuit/subscribers"
 require "standard_circuit/config"
 require "standard_circuit/health"
 require "standard_circuit/runner"
 require "standard_circuit/mailer/circuit_open_error"
 require "standard_circuit/mailer/delivery_method"
 require "standard_circuit/controller_support"
+require "standard_circuit/engine" if defined?(::Rails::Engine)
 
 module StandardCircuit
   class Error < StandardError; end
@@ -27,6 +31,7 @@ module StandardCircuit
     def configure
       yield config
       runner.apply_config!(config)
+      subscribers.setup!
       config
     end
 
@@ -38,6 +43,10 @@ module StandardCircuit
       @runner ||= Runner.new
     end
 
+    def subscribers
+      @subscribers ||= Subscribers.new
+    end
+
     def run(name, fallback: nil, &block)
       runner.run(name, fallback: fallback, &block)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_circuit
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -65,6 +65,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: brakeman
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: StandardCircuit wraps the stoplight gem with opinionated error taxonomy,
   Sentry notifiers, ActiveStorage S3 and ActionMailer adapters, and test helpers shared
   across Rails apps.
@@ -75,10 +117,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- LICENSE
 - README.md
 - Rakefile
 - lib/active_storage/service/standard_circuit_s3_service.rb
+- lib/generators/standard_circuit/install/install_generator.rb
+- lib/generators/standard_circuit/install/templates/health_initializer.rb.tt
+- lib/generators/standard_circuit/install/templates/initializer.rb.tt
 - lib/standard_circuit.rb
 - lib/standard_circuit/active_storage/s3_service.rb
 - lib/standard_circuit/adapter_errors/aws.rb
@@ -87,17 +132,21 @@ files:
 - lib/standard_circuit/adapter_errors/stripe.rb
 - lib/standard_circuit/config.rb
 - lib/standard_circuit/controller_support.rb
+- lib/standard_circuit/engine.rb
 - lib/standard_circuit/error_taxonomies.rb
+- lib/standard_circuit/event_emitter.rb
 - lib/standard_circuit/health.rb
 - lib/standard_circuit/health_controller.rb
 - lib/standard_circuit/mailer/circuit_open_error.rb
 - lib/standard_circuit/mailer/delivery_method.rb
 - lib/standard_circuit/network_errors.rb
+- lib/standard_circuit/notifier_bridge.rb
 - lib/standard_circuit/notifiers/logger.rb
 - lib/standard_circuit/notifiers/metrics.rb
 - lib/standard_circuit/notifiers/sentry.rb
 - lib/standard_circuit/rspec.rb
 - lib/standard_circuit/runner.rb
+- lib/standard_circuit/subscribers.rb
 - lib/standard_circuit/version.rb
 homepage: https://github.com/rarebit-one/standard_circuit
 licenses:
@@ -114,7 +163,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/MIT-LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Jaryl Sim
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be 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.