otp-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3fafef6955d1e366ba5cd01039a7c903a17eee4342a4179e679ecccd75fbab89
+  data.tar.gz: '09f381af732986cdb5f2bea354e3b657009d342ff340bcbf95c6e7f15c9096b6'
+SHA512:
+  metadata.gz: f4da29b3dd961433aefde893f2eecd8165a50ca0720ca301fa71f10cab656e862a415afc86e4f1f9201f15ebd27cf49c80af3e118c730fc522fdfff5790347a7
+  data.tar.gz: 1c74adf968934165f36f379a01bb9dd8cea47b00c0c33d1c3ee8ba2b21eb829358a4e1b6b7c66362dc0c5f52e6eeabbbcbe7ff108a0761ca76df7f62e8a4e87b

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## v0.1.0 — 2026-09-12
+
+First release: a slim, zero-runtime-dependency, OTP-style process supervisor for the
+processes of a Rails app. The supervisor never loads Rails (DESIGN §9).
+
+- **Supervision core** — `ChildSpec` with `permanent`/`transient`/`temporary` restart
+  semantics; `one_for_one`, `rest_for_one`, `one_for_all` strategies; restart intensity
+  with a sliding window that escalates (exit 70) when exceeded; `none`/`constant`/
+  `exponential` backoff; generation-guarded exit handling (stale exits ignored).
+- **Shutdown correctness** (#1) — `stop_all` drains in reverse start order, waiting per
+  child (SIGTERM, then SIGKILL of the process group after `shutdown:`). Exit codes:
+  0 clean, 70 escalation, 78 config error. Orphan prevention on Linux via
+  `prctl(PR_SET_PDEATHSIG, SIGTERM)`; macOS has no equivalent (documented limitation).
+- **Passive probes** (#2) — `probe: { tcp: PORT }` / `probe: { http: URL }` on `:command`:
+  `:starting` until the probe answers, then `:healthy`. `start_timeout` exceeded ⇒ drain ⇒
+  counts as a crash ⇒ strategy applies.
+- **Periodic health loop** (#3) — per-child monitor at `health_interval` (default 5s);
+  `:degraded` emits telemetry only; `degraded_restart_after: N` drains after N consecutive
+  degraded reports (flows through the crash path, so intensity applies).
+- **`:puma` adapter, beside mode** (#4) — wraps the puma master; health = HTTP `/up` probe;
+  drain = SIGTERM (Puma graceful). `opts[:port]` or a literal `port NNNN` in the config.
+- **Active heartbeat socket** (#5) — Unix socket (default `tmp/otp-rails.sock`, mode 0600),
+  per-boot token via `OTP_RAILS_SOCK` / `OTP_RAILS_TOKEN`; NDJSON heartbeats
+  `{"id","state","ts","token","meta"}`; bad token dropped; 3 missed intervals ⇒ `:degraded`,
+  6 ⇒ `:dead` ⇒ restart; `{"cmd":"restart","id":...}` control messages. This wire protocol
+  is the contract consumed by the Elixir sidecar (`shishi-odoshi/beam`).
+- **`:solid_queue` adapter + heartbeat helper** (#6) — wraps `bin/jobs`; health = active
+  heartbeat, not the DB table. `require "otp_rails/heartbeat"` is Rails-free and
+  self-contained; silently a no-op when unsupervised.
+- **Nested supervisors** (#7) — `supervisor :background do ... end` creates a subtree with
+  its own strategy/intensity/backoff; subtree escalation is an ordinary child exit in the
+  parent; restarted subtrees get a fresh intensity window.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim
+
+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

@@ -0,0 +1,149 @@
+# otp-rails
+
+OTP-style supervision trees for the processes of a Rails app. A slim supervisor — it never
+loads Rails — that starts, links, health-checks, and restarts `web`, `jobs`, `cable`, `cron`
+with `one_for_one` / `rest_for_one` / `one_for_all` strategies, restart intensity, and backoff.
+
+Part of the [shishi-odoshi](https://github.com/shishi-odoshi) org. Design: `docs/DESIGN.md`.
+The Elixir sidecar speaking the same wire protocol lives at
+[shishi-odoshi/beam](https://github.com/shishi-odoshi/beam).
+
+## Install
+
+```ruby
+# Gemfile — the supervisor is its own process; a :supervisor group keeps app boot slim
+group :supervisor do
+  gem "otp-rails"
+end
+```
+
+```
+$ bundle install
+$ otp-rails version
+```
+
+Zero runtime dependencies. Ruby >= 3.2.
+
+## Quick start
+
+```ruby
+# config/supervisor.rb — plain Ruby, evaluated WITHOUT Rails
+strategy :rest_for_one
+max_restarts 5, within: 60
+backoff :exponential, base: 1, cap: 30
+
+child :web,  adapter: :puma, port: 3000
+child :jobs, adapter: :solid_queue, shutdown: 60
+child :cron, adapter: :command, cmd: "bin/rails cron", restart: :transient
+```
+
+```
+$ otp-rails check config/supervisor.rb   # validate config, print the tree
+$ otp-rails run   config/supervisor.rb   # supervise (Ctrl-C drains and stops)
+```
+
+## Config reference
+
+Top-level directives in `config/supervisor.rb`:
+
+| Directive | Default | Meaning |
+|---|---|---|
+| `strategy KIND` | `:one_for_one` | `:one_for_one` restarts only the failed child; `:rest_for_one` also restarts children declared after it; `:one_for_all` restarts every child |
+| `max_restarts N, within: S` | `5, within: 60` | Sliding-window restart intensity; exceeding it escalates (exit 70) |
+| `backoff KIND, **opts` | `:exponential, base: 1, cap: 30` | `:none`, `:constant`, or `:exponential` delay between restarts |
+| `socket PATH` | `"tmp/otp-rails.sock"` | Heartbeat/control Unix socket; `socket nil` disables it |
+| `child ID, adapter:, **opts` | — | Declares a child; declaration order is start order |
+| `supervisor ID do ... end` | — | Nested subtree with its own strategy/intensity/backoff; subtree escalation is an ordinary child exit in the parent |
+
+Per-child options:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `restart:` | `:permanent` | `:permanent` always restarts; `:transient` restarts only on non-zero exit; `:temporary` never restarts |
+| `shutdown:` | `30` | Seconds to wait after SIGTERM before SIGKILL of the child's process group |
+| `start_timeout:` | `30` | Seconds to reach `:healthy`; exceeding it drains the child and counts as a crash |
+| `health_interval:` | `5` | Seconds between health checks (and the unit for heartbeat freshness) |
+| `degraded_restart_after:` | `nil` | N consecutive `:degraded` reports ⇒ drain and restart (counts toward intensity) |
+
+Adapters:
+
+- **`:command`** — any command. `cmd:` (required), `env:`, `spawn_opts:`, and optional
+  `probe: { tcp: PORT }` or `probe: { http: "http://127.0.0.1:3000/up" }` — the child is
+  `:starting` until the probe answers, `:degraded` if it stops answering later.
+- **`:puma`** (beside mode) — wraps the puma master. `config:` (default `config/puma.rb`),
+  `port:` (or a literal `port NNNN` line in the config). Health = HTTP probe of `/up`;
+  drain = SIGTERM (Puma's graceful stop).
+- **`:solid_queue`** — wraps `bin/jobs` (`cmd:` overrides). Health = the active heartbeat
+  below, never the `solid_queue_processes` table.
+
+## Health & heartbeats
+
+Passive children are probed (PID, TCP, HTTP). Active children report themselves: the
+supervisor listens on a Unix socket (mode 0600) and exports `OTP_RAILS_SOCK` /
+`OTP_RAILS_TOKEN` to every child. Heartbeats are newline-delimited JSON:
+
+```json
+{"id":"jobs","state":"healthy","ts":1757700000,"token":"…","meta":{"backlog":0}}
+```
+
+A child that has heartbeated is judged by heartbeat freshness: 3 missed `health_interval`s
+⇒ `:degraded`, 6 ⇒ `:dead` ⇒ the strategy applies. Wrong token ⇒ the line is silently
+dropped. The same socket accepts `{"cmd":"restart","id":"jobs","token":"…"}`.
+
+From any child process (a Rails initializer, a Solid Queue hook — no Rails required):
+
+```ruby
+require "otp_rails/heartbeat"   # loads nothing else
+OtpRails::Heartbeat.start(id: "jobs")  # no-op when running unsupervised
+```
+
+## Telemetry reference
+
+Event names follow `[:otp_rails, :subject, :action]`, mirroring Elixir `:telemetry` so the
+sidecar can forward them unchanged. This list is a published contract:
+
+```
+[:otp_rails, :supervisor, :start]     metadata: {strategy, children}
+[:otp_rails, :supervisor, :stop]
+[:otp_rails, :supervisor, :escalate]  measurements: {restarts}  metadata: {within}
+[:otp_rails, :child, :spawn]          metadata: {id, adapter, pid}
+[:otp_rails, :child, :healthy]        metadata: {id}
+[:otp_rails, :child, :degraded]       measurements: {consecutive}  metadata: {id}
+[:otp_rails, :child, :exit]           measurements: {exit_code, uptime_ms}  metadata: {id}
+[:otp_rails, :child, :restart]        measurements: {backoff_ms}  metadata: {id, attempt, strategy}
+[:otp_rails, :child, :drain]          metadata: {id}
+[:otp_rails, :child, :kill]           metadata: {id}  (drain timed out)
+```
+
+Subscribe in-process with `OtpRails::Telemetry.subscribe { |event| ... }`; a logger
+subscriber and a JSON-lines exporter ship by default (`Telemetry::Subscribers`).
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean stop (SIGINT/SIGTERM, all children drained) |
+| `70` | Restart intensity exceeded — the supervisor escalated (EX_SOFTWARE). The platform (Kamal/K8s/Heroku/launchd) is the final supervisor and should restart on non-zero |
+| `78` | Configuration error (EX_CONFIG) |
+
+## Shutdown semantics
+
+- `stop_all` drains children in **reverse start order**, waiting for each child to exit
+  (up to its `shutdown:` timeout, then SIGKILL of its process group) before draining the next.
+- Orphan prevention: on Linux, children are armed with `prctl(PR_SET_PDEATHSIG, SIGTERM)`
+  between fork and exec, so they receive SIGTERM even if the supervisor is SIGKILLed.
+  **macOS/BSD limitation:** no parent-death signal exists there; a SIGKILLed supervisor
+  orphans its children to launchd/init and they keep running. Mitigation: the platform
+  restarts the supervisor; each child runs in its own session/process group, so stale
+  orphans are findable and killable by pgid.
+- macOS also caps Unix socket paths at ~104 bytes — keep `socket PATH` short.
+
+## Development
+
+```
+bundle exec rake test                        # full suite (real processes, no mocks)
+ruby -Ilib -Itest test/supervisor_kill_test.rb
+exe/otp-rails check examples/supervisor.rb
+```
+
+`docs/PLAN.md` is the backlog; `docs/DESIGN.md` is the frozen design.

data/exe/otp-rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require_relative "../lib/otp_rails"
+exit OtpRails::CLI.run(ARGV)

data/lib/otp_rails/adapter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module OtpRails
+  # DESIGN §4. Exactly four operations (+ kill as last resort). Adapters never talk to each other.
+  class Adapter
+    REGISTRY = {}
+
+    def self.register(name, klass) = REGISTRY[name] = klass
+    def self.lookup(name) = REGISTRY.fetch(name) { raise ConfigError, "no adapter registered as #{name.inspect}" }
+
+    # @return [Object] opaque handle
+    def spawn(spec) = raise NotImplementedError
+    # Register a one-shot callback: block.call(exit_status)
+    def link(handle, &on_exit) = raise NotImplementedError
+    # @return [:starting, :healthy, :degraded, :dead]
+    def health(handle) = raise NotImplementedError
+    # Stop accepting work, finish in-flight, exit. Return true if exited within timeout.
+    def drain(handle, timeout:) = raise NotImplementedError
+    # Last resort after drain times out.
+    def kill(handle) = raise NotImplementedError
+  end
+end

data/lib/otp_rails/adapters/command.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+module OtpRails
+  module Adapters
+    # DESIGN §4.1 :command — arbitrary command. Health = PID alive (+ optional probe, TODO).
+    class Command < Adapter
+      Handle = Struct.new(:pid, :spec, :started_at, :exit_status, :waiter, :healthy_once)
+
+      def spawn(spec)
+        cmd = spec.opts.fetch(:cmd) { raise ConfigError, "#{spec.id}: :command adapter requires cmd:" }
+        env = spec.opts.fetch(:env, {}).transform_keys(&:to_s)
+        spawn_opts = spec.opts.fetch(:spawn_opts, {})
+        pid =
+          if OrphanGuard.available?
+            parent = Process.pid
+            Process.fork do
+              Process.setsid # own session ⇒ own pgroup, same as pgroup: true below
+              OrphanGuard.arm!(parent)
+              begin
+                Process.exec(env, cmd, **spawn_opts)
+              rescue SystemCallError
+                Process.exit!(127)
+              end
+            end
+          else
+            Process.spawn(env, cmd, pgroup: true, **spawn_opts)
+          end
+        Handle.new(pid, spec, Process.clock_gettime(Process::CLOCK_MONOTONIC), nil, nil)
+      end
+
+      def link(handle, &on_exit)
+        handle.waiter = Thread.new do
+          _, status = Process.wait2(handle.pid)
+          handle.exit_status = status
+          on_exit.call(status)
+        rescue Errno::ECHILD
+          on_exit.call(nil)
+        end
+      end
+
+      def health(handle)
+        return :dead if handle.exit_status
+        Process.kill(0, handle.pid)
+        if Probe.answering?(handle.spec)
+          handle.healthy_once = true
+          :healthy
+        elsif handle.healthy_once
+          :degraded # was healthy, probe stopped answering, PID still alive (§5)
+        else
+          :starting
+        end
+      rescue Errno::ESRCH
+        :dead
+      end
+
+      def drain(handle, timeout:)
+        Process.kill("TERM", handle.pid)
+        handle.waiter&.join(timeout)
+        !handle.exit_status.nil?
+      rescue Errno::ESRCH
+        true
+      end
+
+      def kill(handle)
+        Process.kill("KILL", -handle.pid) # whole process group
+        handle.waiter&.join(2)
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+  Adapter.register(:command, Adapters::Command)
+end

data/lib/otp_rails/adapters/puma.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+module OtpRails
+  module Adapters
+    # DESIGN §4.1 / §4.2 step 1 — :puma in "beside" mode: one opaque child
+    # wrapping the puma master. Health = HTTP probe of /up (the Rails 7.1+
+    # default endpoint) on the bound port; drain = SIGTERM, which is Puma's
+    # graceful shutdown — exactly Command#drain, so it is inherited unchanged,
+    # as are link and kill.
+    #
+    # The whole adapter is Command with a derived spec: spawn builds the puma
+    # command line and injects a probe: { http: ".../up" } opt, so health()
+    # rides the PLAN 1.2 Probe path with no new code — :starting until /up
+    # answers 2xx, then :healthy; :dead when the PID goes.
+    #
+    # opts:
+    #   config:     puma config file path (default "config/puma.rb")
+    #   port:       the bound port. When absent, a literal `port NNNN` line is
+    #               parsed from the config file; neither ⇒ ConfigError.
+    #   env:, spawn_opts:  passed through to Command verbatim.
+    #   (cmd: and probe: are owned by this adapter and overwritten.)
+    class Puma < Command
+      DEFAULT_CONFIG = "config/puma.rb"
+      HEALTH_PATH = "/up"
+
+      def spawn(spec)
+        super(command_spec(spec))
+      end
+
+      private
+
+      def command_spec(spec)
+        config = spec.opts.fetch(:config, DEFAULT_CONFIG)
+        port = resolve_port(spec, config)
+        ChildSpec.new(
+          id: spec.id, adapter: spec.adapter, restart: spec.restart,
+          shutdown: spec.shutdown, start_timeout: spec.start_timeout,
+          opts: spec.opts.merge(
+            cmd: "bundle exec puma -C #{config}",
+            probe: { http: "http://127.0.0.1:#{port}#{HEALTH_PATH}" }
+          )
+        )
+      end
+
+      # opts[:port] wins; else a literal `port NNNN` line in the config file.
+      # Anything fancier (ENV/ERB in the config) must pass opts[:port].
+      def resolve_port(spec, config)
+        return Integer(spec.opts[:port]) if spec.opts[:port]
+        literal = File.file?(config) && File.read(config)[/^\s*port\s+(\d+)/, 1]
+        return Integer(literal) if literal
+        raise ConfigError,
+              "#{spec.id}: :puma needs opts[:port] or a literal `port NNNN` line in #{config}"
+      end
+    end
+  end
+  Adapter.register(:puma, Adapters::Puma)
+end

data/lib/otp_rails/adapters/solid_queue.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+module OtpRails
+  module Adapters
+    # DESIGN §4.1 / §9 — :solid_queue wraps the Solid Queue supervisor
+    # (`bin/jobs`). Health is the ACTIVE heartbeat (§5), NOT the
+    # solid_queue_processes table: the app sends heartbeats via the tiny
+    # Rails-free hook, e.g. from an initializer:
+    #
+    #   require "otp_rails/heartbeat"
+    #   OtpRails::Heartbeat.start(id: "jobs")
+    #
+    # Once the first heartbeat arrives the supervisor judges the child by
+    # heartbeat freshness (3 missed intervals ⇒ :degraded, 6 ⇒ :dead);
+    # until then it falls back to this adapter's passive PID health,
+    # inherited from Command — as are link, drain (SIGTERM, which Solid
+    # Queue handles gracefully), and kill.
+    #
+    # opts:
+    #   cmd:  the jobs command (default "bin/jobs")
+    #   env:, spawn_opts:  passed through to Command verbatim.
+    class SolidQueue < Command
+      DEFAULT_CMD = "bin/jobs"
+
+      def spawn(spec)
+        super(command_spec(spec))
+      end
+
+      private
+
+      def command_spec(spec)
+        ChildSpec.new(
+          id: spec.id, adapter: spec.adapter, restart: spec.restart,
+          shutdown: spec.shutdown, start_timeout: spec.start_timeout,
+          opts: spec.opts.merge(cmd: spec.opts.fetch(:cmd, DEFAULT_CMD))
+        )
+      end
+    end
+  end
+  Adapter.register(:solid_queue, Adapters::SolidQueue)
+end

data/lib/otp_rails/adapters/supervisor_adapter.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+module OtpRails
+  module Adapters
+    # DESIGN §3.1 nested supervisors. A subtree is just another child of the
+    # parent: this pseudo-adapter runs a child Supervisor on a Thread and maps
+    # the four adapter operations onto it. Escalation inside the subtree
+    # terminates the thread, which surfaces to the parent as a crashed exit —
+    # the parent then applies ITS strategy/intensity to the subtree child
+    # (restart the whole subtree, etc.), exactly per OTP semantics.
+    #
+    # opts:
+    #   builder: a Proc returning a FRESH OtpRails::Supervisor each call.
+    #            A restarted subtree must not inherit the old subtree's
+    #            RestartIntensity window (it is stateful), so spawn re-invokes
+    #            the builder on every (re)start instead of reusing an instance.
+    class SupervisorAdapter < Adapter
+      # Duck-types the two things the tree asks of an exit status:
+      # #exitstatus (telemetry) and #success? (ChildSpec#restart? semantics).
+      Status = Struct.new(:exitstatus) do
+        def success? = exitstatus == 0
+      end
+
+      Handle = Struct.new(:sub, :thread, :started_at, :exit_status, :waiter, :killed)
+
+      def spawn(spec)
+        builder = spec.opts.fetch(:builder) do
+          raise ConfigError, "#{spec.id}: :supervisor adapter requires builder: (a proc returning a fresh Supervisor)"
+        end
+        sub = builder.call
+        raise ConfigError, "#{spec.id}: builder must return an OtpRails::Supervisor" unless sub.is_a?(Supervisor)
+        thread = Thread.new { sub.run }
+        # Escalation out of a subtree is an expected, handled exit path — the
+        # waiter converts it into a crashed status. Don't let Ruby dump it.
+        thread.report_on_exception = false
+        Handle.new(sub, thread, Process.clock_gettime(Process::CLOCK_MONOTONIC), nil, nil, false)
+      end
+
+      def link(handle, &on_exit)
+        handle.waiter = Thread.new do
+          status =
+            begin
+              handle.thread.join # re-raises whatever terminated the subtree
+              Status.new(handle.killed ? nil : 0)
+            rescue Escalation
+              Status.new(70) # crashed: intensity exceeded inside the subtree
+            rescue StandardError
+              Status.new(1)  # crashed: unexpected error in the subtree loop
+            end
+          handle.exit_status = status
+          on_exit.call(status)
+        end
+      end
+
+      # The subtree's internal health is its own supervisor's business; from
+      # the parent's seat the subtree is healthy while its loop is running.
+      # Death also arrives via link, so parents normally give subtree specs
+      # health_interval: nil (the DSL does) and skip the probe monitor.
+      def health(handle)
+        handle.thread.alive? ? :healthy : :dead
+      end
+
+      # Clean stop: the subtree's run loop breaks and its `ensure stop_all`
+      # drains the subtree's own children (reverse order) before the thread
+      # exits — so by the time this returns true, no subtree PIDs remain.
+      def drain(handle, timeout:)
+        handle.sub.stop
+        joined =
+          begin
+            handle.thread.join(timeout)
+          rescue StandardError
+            handle.thread # join re-raised => the thread has terminated
+          end
+        !joined.nil?
+      end
+
+      # Last resort. Thread#kill still runs the subtree's `ensure stop_all`;
+      # if even that wedges, best-effort drain the subtree's children directly
+      # so no grandchild PIDs are orphaned.
+      def kill(handle)
+        handle.killed = true
+        handle.thread.kill
+        joined =
+          begin
+            handle.thread.join(2)
+          rescue StandardError
+            handle.thread
+          end
+        handle.sub.send(:stop_all) if joined.nil? # loop wedged: drain grandchildren ourselves
+      rescue StandardError
+        nil
+      end
+    end
+  end
+  Adapter.register(:supervisor, Adapters::SupervisorAdapter)
+end

data/lib/otp_rails/backoff.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+module OtpRails
+  class Backoff
+    def initialize(kind: :exponential, base: 1.0, cap: 30.0)
+      @kind, @base, @cap = kind, base.to_f, cap.to_f
+    end
+
+    # attempt is 1-based
+    def delay(attempt)
+      case @kind
+      when :none        then 0.0
+      when :constant    then @base
+      when :exponential then [@base * (2**(attempt - 1)), @cap].min
+      else raise ConfigError, "unknown backoff #{@kind}"
+      end
+    end
+  end
+end

data/lib/otp_rails/child_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+module OtpRails
+  # DESIGN §3.2
+  class ChildSpec
+    RESTART_KINDS = %i[permanent transient temporary].freeze
+
+    attr_reader :id, :adapter, :restart, :shutdown, :start_timeout, :health_interval,
+                :degraded_restart_after, :opts
+
+    def initialize(id:, adapter:, restart: :permanent, shutdown: 30, start_timeout: 30,
+                   health_interval: 5, degraded_restart_after: nil, opts: {})
+      raise ConfigError, "child id must be a Symbol" unless id.is_a?(Symbol)
+      raise ConfigError, "restart must be one of #{RESTART_KINDS}" unless RESTART_KINDS.include?(restart)
+      @id, @adapter, @restart, @shutdown, @start_timeout, @opts =
+        id, adapter, restart, shutdown, start_timeout, opts
+      @health_interval, @degraded_restart_after = health_interval, degraded_restart_after
+    end
+
+    # Should this child be restarted given how it exited? (OTP semantics)
+    def restart?(exit_status)
+      case restart
+      when :permanent then true
+      when :transient then !normal_exit?(exit_status)
+      when :temporary then false
+      end
+    end
+
+    def normal_exit?(status)
+      return false if status.nil?
+      status.respond_to?(:success?) ? status.success? : status.to_i.zero?
+    end
+  end
+end

data/lib/otp_rails/cli.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+module OtpRails
+  module CLI
+    USAGE = <<~TXT
+      usage: otp-rails run   [config/supervisor.rb]   # start the tree, block until shutdown
+             otp-rails check [config/supervisor.rb]   # validate config, print the tree
+             otp-rails version
+    TXT
+
+    def self.run(argv)
+      cmd, path = argv[0], (argv[1] || "config/supervisor.rb")
+      case cmd
+      when "run"
+        Telemetry::Subscribers.logger
+        sup = DSL.load_file(path)
+        %w[INT TERM].each { |sig| trap(sig) { sup.stop } }
+        sup.run
+        0
+      when "check"
+        sup = DSL.load_file(path)
+        puts "strategy: #{sup.strategy}"
+        sup.children.each { |c| puts "  #{c.id} (#{c.adapter}, #{c.restart}, shutdown=#{c.shutdown}s)" }
+        0
+      when "version" then puts VERSION; 0
+      else $stderr.puts USAGE; 1
+      end
+    rescue Escalation => e
+      $stderr.puts "otp-rails: #{e.message}"; 70 # EX_SOFTWARE — the platform is the final supervisor
+    rescue ConfigError, Errno::ENOENT => e
+      $stderr.puts "otp-rails: #{e.message}"; 78 # EX_CONFIG
+    end
+  end
+end

data/lib/otp_rails/dsl.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+module OtpRails
+  # Evaluates config/supervisor.rb WITHOUT Rails loaded (DESIGN §9).
+  #
+  #   strategy :rest_for_one
+  #   max_restarts 5, within: 60
+  #   backoff :exponential, base: 1, cap: 30
+  #   child :web,  adapter: :command, cmd: "bundle exec puma -C config/puma.rb"
+  #   child :jobs, adapter: :command, cmd: "bin/jobs"
+  #   supervisor :background do          # DESIGN §3.1: nested subtree with its
+  #     strategy :one_for_all            # own strategy/intensity/backoff
+  #     child :cron, adapter: :command, cmd: "bin/rails cron"
+  #   end
+  class DSL
+    def self.load_file(path)
+      dsl = new
+      dsl.instance_eval(File.read(path), path, 1)
+      dsl.build
+    end
+
+    def initialize(root: true)
+      @root = root
+      @strategy = :one_for_one
+      @intensity = { max_restarts: 5, within: 60 }
+      @backoff = { kind: :exponential, base: 1, cap: 30 }
+      @children = []
+      # DESIGN §5/§9 default; socket nil disables. Only the ROOT supervisor
+      # listens — subtrees never bind their own socket.
+      @socket_path = root ? "tmp/otp-rails.sock" : nil
+    end
+
+    def strategy(kind) = @strategy = kind
+    def max_restarts(n, within:) = @intensity = { max_restarts: n, within: within }
+    def backoff(kind, **opts) = @backoff = { kind: kind, **opts }
+
+    def socket(path)
+      raise ConfigError, "socket can only be set on the root supervisor" unless @root
+      @socket_path = path
+    end
+
+    # DESIGN §3.1: `supervisor :background do ... end` creates a subtree — a
+    # :supervisor child whose block supports the full DSL (strategy /
+    # max_restarts / backoff / child, and further nesting). The block is kept
+    # as a builder so every (re)start constructs a FRESH child Supervisor:
+    # RestartIntensity is stateful, and a restarted subtree must start with a
+    # clean intensity window.
+    def supervisor(id, restart: :permanent, shutdown: 30, start_timeout: 30, &block)
+      raise ConfigError, "supervisor #{id.inspect} requires a block" unless block
+      builder = lambda do
+        sub = DSL.new(root: false)
+        sub.instance_eval(&block)
+        sub.build
+      end
+      builder.call # fail fast at config load, not at spawn time
+      # health_interval nil: subtree liveness arrives via link (thread death),
+      # and its internal health is the subtree supervisor's own business — no
+      # probe monitor needed in the parent.
+      @children << ChildSpec.new(id: id, adapter: :supervisor, restart: restart,
+                                 shutdown: shutdown, start_timeout: start_timeout,
+                                 health_interval: nil, opts: { builder: builder })
+    end
+
+    def child(id, adapter:, restart: :permanent, shutdown: 30, start_timeout: 30,
+              health_interval: 5, degraded_restart_after: nil, **opts)
+      @children << ChildSpec.new(id: id, adapter: adapter, restart: restart, shutdown: shutdown,
+                                 start_timeout: start_timeout, health_interval: health_interval,
+                                 degraded_restart_after: degraded_restart_after, opts: opts)
+    end
+
+    def build
+      sup = Supervisor.new(strategy: @strategy,
+                           intensity: RestartIntensity.new(**@intensity),
+                           backoff: Backoff.new(**@backoff),
+                           socket_path: @socket_path)
+      @children.each { |c| sup.add_child(c) }
+      sup
+    end
+  end
+
+  def self.supervise(&block)
+    dsl = DSL.new
+    dsl.instance_eval(&block)
+    dsl.build
+  end
+end

data/lib/otp_rails/heartbeat.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+require "socket"
+require "json"
+
+# Deliberately self-contained (PLAN 1.6): any child process can
+#   require "otp_rails/heartbeat"
+# without loading the rest of the gem — e.g. from a Rails initializer or a
+# Solid Queue hook — and never Rails itself (hard rule 1 / DESIGN §9).
+module OtpRails
+  # Sends DESIGN §5 NDJSON heartbeats to the supervising socket:
+  #
+  #   OtpRails::Heartbeat.start(id: "jobs")
+  #   OtpRails::Heartbeat.start(id: "jobs", interval: 2,
+  #                             state: -> { queue_backlog_ok? ? "healthy" : "degraded" },
+  #                             meta:  -> { { backlog: backlog_size } })
+  #
+  # Silently a no-op when OTP_RAILS_SOCK / OTP_RAILS_TOKEN are absent — the
+  # child is running unsupervised (plain `bin/jobs` in development) and that
+  # must not be an error. Reconnects on socket loss; never raises into the
+  # host process.
+  class Heartbeat
+    def self.start(id:, interval: 2, state: -> { "healthy" }, meta: -> { {} })
+      new(id: id, interval: interval, state: state, meta: meta).start
+    end
+
+    def initialize(id:, interval: 2, state: -> { "healthy" }, meta: -> { {} })
+      @id, @interval, @state, @meta = id.to_s, interval, state, meta
+      @sock_path, @token = ENV["OTP_RAILS_SOCK"], ENV["OTP_RAILS_TOKEN"]
+    end
+
+    # Returns the beating thread, or nil when unsupervised.
+    def start
+      return nil unless @sock_path && @token
+      @thread = Thread.new do
+        sock = nil
+        loop do
+          begin
+            sock ||= UNIXSocket.new(@sock_path)
+            sock.puts(JSON.generate(id: @id, state: @state.call, ts: Time.now.to_i,
+                                    token: @token, meta: @meta.call))
+          rescue IOError, SystemCallError
+            sock = nil # supervisor gone or restarting; try again next beat
+          end
+          sleep @interval
+        end
+      end
+    end
+
+    def stop = @thread&.kill
+  end
+end

data/lib/otp_rails/orphan_guard.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module OtpRails
+  # PLAN 1.1 orphan prevention: if the supervisor is SIGKILLed, children should
+  # still receive SIGTERM. Linux delivers this via prctl(PR_SET_PDEATHSIG),
+  # armed in the forked child between fork and exec. macOS/BSD have no
+  # equivalent: children there are re-parented to launchd/init and keep running
+  # until the platform supervisor reaps them (documented limitation, README).
+  module OrphanGuard
+    PR_SET_PDEATHSIG = 1
+
+    def self.available?
+      return @available if defined?(@available)
+      @available = RUBY_PLATFORM.include?("linux") && fiddle?
+    end
+
+    def self.fiddle?
+      require "fiddle"
+      true
+    rescue LoadError
+      false
+    end
+
+    # Runs in the forked child, pre-exec. parent_pid is the supervisor's pid at
+    # fork time: pdeathsig is not delivered if the parent died before prctl ran,
+    # so re-check the parent afterwards and exit rather than run orphaned.
+    def self.arm!(parent_pid, signal: "TERM")
+      return false unless available?
+      libc = Fiddle.dlopen(nil)
+      prctl = Fiddle::Function.new(libc["prctl"], [Fiddle::TYPE_INT] * 5, Fiddle::TYPE_INT)
+      armed = prctl.call(PR_SET_PDEATHSIG, Signal.list.fetch(signal), 0, 0, 0).zero?
+      Process.exit!(0) if Process.ppid != parent_pid
+      armed
+    end
+  end
+end

data/lib/otp_rails/probe.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+require "socket"
+require "net/http"
+require "uri"
+
+module OtpRails
+  # Passive probes (DESIGN §4.1/§5): a child declared with probe: opts is
+  # :starting until the probe answers, then :healthy. Probes are adapter
+  # plumbing behind health(), not part of the Adapter interface (hard rule 2).
+  #
+  #   probe: { tcp: 5432 }
+  #   probe: { http: "http://127.0.0.1:3000/up" }
+  module Probe
+    CONNECT_TIMEOUT = 0.25
+    READ_TIMEOUT = 0.5
+
+    # true when the probe answers (or the spec declares no probe).
+    def self.answering?(spec)
+      probe = spec.opts[:probe] or return true
+      if (port = probe[:tcp])
+        tcp?(port)
+      elsif (url = probe[:http])
+        http?(url)
+      else
+        raise ConfigError, "#{spec.id}: probe must be {tcp: PORT} or {http: URL}, got #{probe.inspect}"
+      end
+    end
+
+    def self.tcp?(port, host = "127.0.0.1")
+      Socket.tcp(host, port, connect_timeout: CONNECT_TIMEOUT) { true }
+    rescue SystemCallError, IO::TimeoutError
+      false
+    end
+
+    def self.http?(url)
+      uri = URI(url)
+      Net::HTTP.start(uri.host, uri.port, open_timeout: CONNECT_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|
+        http.get(uri.path.empty? ? "/" : uri.path).code.to_i.between?(200, 299)
+      end
+    rescue SystemCallError, IO::TimeoutError, Net::OpenTimeout, Net::ReadTimeout, EOFError
+      false
+    end
+  end
+end

data/lib/otp_rails/restart_intensity.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+module OtpRails
+  # OTP restart intensity: more than `max_restarts` within `within` seconds => escalate.
+  class RestartIntensity
+    attr_reader :max_restarts, :within
+
+    def initialize(max_restarts: 5, within: 60, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @max_restarts, @within, @clock = max_restarts, within, clock
+      @events = []
+    end
+
+    # Records a restart. Returns true if the supervisor should escalate (give up).
+    def record!
+      now = @clock.call
+      @events << now
+      @events.reject! { |t| now - t > @within }
+      @events.size > @max_restarts
+    end
+
+    def count = @events.size
+  end
+end

data/lib/otp_rails/socket_server.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+require "socket"
+require "json"
+require "securerandom"
+require "fileutils"
+
+module OtpRails
+  # DESIGN §5 active heartbeats + §9 control transport, PLAN 1.4.
+  # Newline-delimited JSON over a Unix socket, mode 0600, per-boot token —
+  # no MessagePack, no length prefixes, no versions (hard rule 4). This wire
+  # format is the contract the Elixir `beam` repo consumes.
+  #
+  # Heartbeat:  {"id":"jobs","state":"healthy","ts":1757700000,"token":"…","meta":{}}
+  # Control:    {"cmd":"restart","id":"jobs","token":"…"}
+  # Any line with a missing or wrong token is dropped without a reply.
+  class SocketServer
+    attr_reader :path, :token
+
+    def initialize(path:, on_heartbeat:, on_control:)
+      @path, @on_heartbeat, @on_control = path, on_heartbeat, on_control
+      @token = SecureRandom.hex(16)
+    end
+
+    # Binds, chmods, and exports OTP_RAILS_SOCK / OTP_RAILS_TOKEN so children
+    # spawned afterwards inherit them (DESIGN §9). Call before starting children.
+    def start
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.unlink(@path) if File.exist?(@path) # stale socket from a dead boot
+      @server = UNIXServer.new(@path)
+      File.chmod(0o600, @path)
+      ENV["OTP_RAILS_SOCK"] = @path
+      ENV["OTP_RAILS_TOKEN"] = @token
+      @acceptor = Thread.new do
+        loop do
+          conn = @server.accept
+          Thread.new { serve(conn) }
+        rescue IOError, SystemCallError
+          break # server closed during shutdown
+        end
+      end
+    end
+
+    def stop
+      @server&.close
+      @acceptor&.kill
+      File.unlink(@path) if File.exist?(@path)
+    rescue SystemCallError
+      nil
+    end
+
+    private
+
+    def serve(conn)
+      conn.each_line do |line|
+        msg = begin
+          JSON.parse(line)
+        rescue JSON::ParserError
+          next
+        end
+        next unless msg["token"] == @token # bad token ⇒ dropped
+        if msg["cmd"]
+          @on_control.call(msg)
+        elsif msg["id"] && msg["state"]
+          @on_heartbeat.call(msg)
+        end
+      end
+    rescue IOError, SystemCallError
+      nil
+    ensure
+      begin
+        conn.close
+      rescue IOError
+        nil
+      end
+    end
+  end
+end

data/lib/otp_rails/strategy.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+module OtpRails
+  # DESIGN §3.3. Given the ordered child ids and the failed id,
+  # return the ordered ids that must be stopped and restarted.
+  module Strategy
+    KINDS = %i[one_for_one rest_for_one one_for_all].freeze
+
+    def self.affected(kind, ordered_ids, failed_id)
+      raise ConfigError, "unknown strategy #{kind}" unless KINDS.include?(kind)
+      idx = ordered_ids.index(failed_id) or raise ArgumentError, "#{failed_id} not in tree"
+      case kind
+      when :one_for_one  then [failed_id]
+      when :rest_for_one then ordered_ids[idx..]
+      when :one_for_all  then ordered_ids.dup
+      end
+    end
+  end
+end

data/lib/otp_rails/supervisor.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+module OtpRails
+  # DESIGN §3.1 / §3.3. One supervisor, an ordered set of children, one strategy.
+  # Nested supervisors (subtrees) are ordinary children via Adapters::SupervisorAdapter:
+  # a subtree escalating shows up here as a crashed child exit.
+  class Supervisor
+    attr_reader :children, :strategy, :intensity, :backoff
+
+    def initialize(strategy: :one_for_one, intensity: RestartIntensity.new, backoff: Backoff.new,
+                   socket_path: nil)
+      raise ConfigError, "unknown strategy #{strategy}" unless Strategy::KINDS.include?(strategy)
+      @strategy, @intensity, @backoff = strategy, intensity, backoff
+      @children = [] # ordered ChildSpecs
+      @live = {}     # id => { adapter:, handle:, attempts:, generation:, monitor: }
+      @queue = Queue.new
+      @stopping = false
+      @heartbeats = {} # id => { at: monotonic ts of last heartbeat, state: reported state }
+      return unless socket_path
+      @socket = SocketServer.new(
+        path: socket_path,
+        on_heartbeat: ->(msg) { @heartbeats[msg["id"].to_sym] = { at: mono_now, state: msg["state"] } },
+        on_control: ->(msg) { @queue << { type: :control, cmd: msg["cmd"], id: msg["id"].to_s.to_sym } }
+      )
+    end
+
+    # The per-boot token children must echo in every heartbeat (nil when the
+    # socket is disabled). Exported to children as OTP_RAILS_TOKEN.
+    def heartbeat_token = @socket&.token
+
+    def add_child(spec)
+      raise ConfigError, "duplicate child id #{spec.id}" if @children.any? { |c| c.id == spec.id }
+      @children << spec
+      self
+    end
+
+    # Blocks until the tree is shut down. Raises Escalation if intensity is exceeded.
+    def run
+      Telemetry.emit(:"supervisor.start", {}, { strategy: strategy, children: ids })
+      @socket&.start # before children, so they inherit OTP_RAILS_SOCK/_TOKEN
+      @children.each { |spec| start_child(spec) }
+      loop do
+        msg = @queue.pop
+        case msg[:type]
+        when :exit then handle_exit(msg[:id], msg[:generation], msg[:status])
+        when :health_dead then handle_health_dead(msg[:id], msg[:generation])
+        when :control then handle_control(msg)
+        when :stop then break
+        end
+      end
+    ensure
+      stop_all
+      @socket&.stop
+      Telemetry.emit(:"supervisor.stop")
+    end
+
+    def stop = @queue << { type: :stop }
+
+    # Public remediation API (DESIGN §7). Over IPC in the real thing; direct call here.
+    def restart!(id)
+      spec = spec_for(id)
+      stop_child(spec)
+      start_child(spec)
+    end
+
+    def ids = @children.map(&:id)
+
+    # Debug/test hook. Not public API.
+    def live_pid(id) = @live.dig(id, :handle)&.pid
+
+    private
+
+    def spec_for(id) = @children.find { |c| c.id == id } || raise(ArgumentError, "no child #{id}")
+
+    def start_child(spec)
+      @heartbeats.delete(spec.id) # a replaced child's heartbeats must not vouch for its successor
+      adapter = Adapter.lookup(spec.adapter).new
+      handle = adapter.spawn(spec)
+      prev = @live[spec.id] || {}
+      generation = (prev[:generation] || 0) + 1
+      @live[spec.id] = { adapter: adapter, handle: handle, attempts: prev[:attempts] || 0, generation: generation }
+      adapter.link(handle) do |status|
+        @queue << { type: :exit, id: spec.id, generation: generation, status: status } unless @stopping
+      end
+      Telemetry.emit(:"child.spawn", {}, { id: spec.id, adapter: spec.adapter, pid: handle.respond_to?(:pid) ? handle.pid : nil })
+      start_monitor(spec, generation) if wait_healthy(spec, adapter, handle) == :healthy
+    end
+
+    # PLAN 1.3: per-child polling thread. :degraded emits telemetry only,
+    # unless degraded_restart_after consecutive reports accumulate; :dead from
+    # a probe (not just SIGCHLD) goes through the exit queue like any crash.
+    def start_monitor(spec, generation)
+      return unless spec.health_interval
+      entry = @live[spec.id]
+      adapter, handle = entry[:adapter], entry[:handle]
+      degraded = 0
+      entry[:monitor] = Thread.new do
+        loop do
+          sleep spec.health_interval
+          break if @stopping || @live.dig(spec.id, :generation) != generation
+          case effective_health(spec, adapter, handle)
+          when :healthy
+            degraded = 0
+          when :degraded
+            degraded += 1
+            Telemetry.emit(:"child.degraded", { consecutive: degraded }, { id: spec.id })
+            if spec.degraded_restart_after && degraded >= spec.degraded_restart_after
+              @queue << { type: :health_dead, id: spec.id, generation: generation }
+              break
+            end
+          when :dead
+            @queue << { type: :health_dead, id: spec.id, generation: generation }
+            break
+          end
+        end
+      end
+    end
+
+    def wait_healthy(spec, adapter, handle)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + spec.start_timeout
+      loop do
+        case effective_health(spec, adapter, handle)
+        when :healthy then Telemetry.emit(:"child.healthy", {}, { id: spec.id }); return :healthy
+        when :dead    then return :dead # the exit message arrives via link
+        end
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          # PLAN 1.2: start_timeout exceeded ⇒ drain. The resulting exit flows
+          # through the normal link → handle_exit path, so it counts as a
+          # crash and the strategy + intensity apply.
+          stop_child(spec)
+          return :timeout
+        end
+        sleep 0.05
+      end
+    end
+
+    HEARTBEAT_STATES = { "starting" => :starting, "healthy" => :healthy,
+                         "degraded" => :degraded, "dead" => :dead }.freeze
+
+    # DESIGN §5/§9: health is active-first. A child that has heartbeated is
+    # judged by heartbeat freshness and its own reported state — missing 3
+    # intervals ⇒ :degraded, 6 ⇒ :dead. Children that never heartbeat fall
+    # back to the adapter's passive probe.
+    def effective_health(spec, adapter, handle)
+      hb = @heartbeats[spec.id]
+      return adapter.health(handle) unless hb
+      missed = (mono_now - hb[:at]) / spec.health_interval
+      return :dead if missed >= 6
+      return :degraded if missed >= 3
+      HEARTBEAT_STATES.fetch(hb[:state], :healthy)
+    end
+
+    def mono_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # DESIGN §7/§9: {"cmd":"restart","id":...} over the socket — the transport
+    # Rails.supervisor.restart! rides later. Unknown commands and ids are
+    # ignored; the token was already checked at the socket layer.
+    def handle_control(msg)
+      return unless msg[:cmd] == "restart"
+      return unless @children.any? { |c| c.id == msg[:id] }
+      restart!(msg[:id])
+    end
+
+    # A monitor thread declared this child unhealthy enough to replace. Drain
+    # it; the resulting real exit flows through link → handle_exit, so the
+    # strategy and intensity apply exactly as for a crash (same path as the
+    # 1.2 start_timeout drain). If the child already exited and was replaced,
+    # the generation guard makes this a no-op.
+    def handle_health_dead(id, generation)
+      entry = @live[id]
+      return if entry.nil? || entry[:generation] != generation
+      stop_child(spec_for(id))
+    end
+
+    def handle_exit(id, generation, status)
+      spec = spec_for(id)
+      entry = @live[id]
+      return if entry.nil? || entry[:generation] != generation # stale exit from a child we already replaced
+
+      uptime = Process.clock_gettime(Process::CLOCK_MONOTONIC) - entry[:handle].started_at
+      Telemetry.emit(:"child.exit", { exit_code: status&.exitstatus, uptime_ms: (uptime * 1000).round }, { id: id })
+      return unless spec.restart?(status)
+
+      if intensity.record!
+        Telemetry.emit(:"supervisor.escalate", { restarts: intensity.count }, { within: intensity.within })
+        raise Escalation, "restart intensity exceeded (#{intensity.count} in #{intensity.within}s)"
+      end
+
+      Strategy.affected(strategy, ids, id).each do |aid|
+        aspec = spec_for(aid)
+        stop_child(aspec) unless aid == id
+        attempts = (@live[aid][:attempts] += 1)
+        delay = backoff.delay(attempts)
+        Telemetry.emit(:"child.restart", { backoff_ms: (delay * 1000).round }, { id: aid, attempt: attempts, strategy: strategy })
+        sleep delay
+        start_child(aspec)
+      end
+    end
+
+    def stop_child(spec)
+      entry = @live[spec.id] or return
+      entry[:monitor]&.kill
+      entry[:monitor] = nil
+      Telemetry.emit(:"child.drain", {}, { id: spec.id })
+      return if entry[:adapter].drain(entry[:handle], timeout: spec.shutdown)
+      Telemetry.emit(:"child.kill", {}, { id: spec.id })
+      entry[:adapter].kill(entry[:handle])
+    end
+
+    def stop_all
+      @stopping = true
+      @children.reverse_each { |spec| stop_child(spec) }
+    end
+  end
+end

data/lib/otp_rails/telemetry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+require "json"
+
+module OtpRails
+  # Minimal event bus. Event names mirror Elixir :telemetry (DESIGN §6):
+  #   event: [:otp_rails, :child, :restart], measurements: {...}, metadata: {...}
+  # A railtie will bridge these into ActiveSupport::Notifications inside children.
+  module Telemetry
+    EVENTS = %i[
+      supervisor.start supervisor.stop supervisor.escalate
+      child.spawn child.healthy child.degraded child.exit child.restart child.drain child.kill
+    ].freeze
+
+    @subscribers = []
+    @mutex = Mutex.new
+
+    class << self
+      def subscribe(&block)
+        @mutex.synchronize { @subscribers << block }
+        block
+      end
+
+      def unsubscribe(block)
+        @mutex.synchronize { @subscribers.delete(block) }
+      end
+
+      def reset!
+        @mutex.synchronize { @subscribers.clear }
+      end
+
+      # name: Symbol like :"child.restart" (flat in Ruby; split on "." for the Elixir side)
+      def emit(name, measurements = {}, metadata = {})
+        raise ArgumentError, "unknown event #{name}" unless EVENTS.include?(name)
+        event = { event: [:otp_rails, *name.to_s.split(".").map(&:to_sym)],
+                  measurements: measurements, metadata: metadata,
+                  ts: Process.clock_gettime(Process::CLOCK_REALTIME) }
+        subs = @mutex.synchronize { @subscribers.dup }
+        subs.each { |s| s.call(event) }
+        event
+      end
+    end
+
+    # Default subscribers shipped in v0.1
+    module Subscribers
+      def self.logger(io = $stderr)
+        Telemetry.subscribe do |e|
+          io.puts("[otp-rails] #{e[:event].join('.')} #{e[:metadata].inspect} #{e[:measurements].inspect}")
+        end
+      end
+
+      def self.json_lines(io = $stdout)
+        Telemetry.subscribe { |e| io.puts(JSON.generate(e)) }
+      end
+    end
+  end
+end

data/lib/otp_rails/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module OtpRails
+  VERSION = "0.1.0"
+end

data/lib/otp_rails.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# otp-rails: a slim, Rails-free process supervisor with OTP semantics.
+# Nothing under lib/otp_rails may require Rails, ActiveSupport, or ActiveRecord (DESIGN §9).
+# The Rails-side bridge (railtie) is a later deliverable and is only ever loaded inside children.
+
+require_relative "otp_rails/version"
+
+module OtpRails
+  class Error < StandardError; end
+  class ConfigError < Error; end
+  class Escalation < Error; end # raised when restart intensity is exceeded
+end
+
+require_relative "otp_rails/telemetry"
+require_relative "otp_rails/child_spec"
+require_relative "otp_rails/strategy"
+require_relative "otp_rails/restart_intensity"
+require_relative "otp_rails/backoff"
+require_relative "otp_rails/adapter"
+require_relative "otp_rails/probe"
+require_relative "otp_rails/orphan_guard"
+require_relative "otp_rails/adapters/command"
+require_relative "otp_rails/adapters/puma"
+require_relative "otp_rails/adapters/solid_queue"
+require_relative "otp_rails/socket_server"
+require_relative "otp_rails/heartbeat"
+require_relative "otp_rails/supervisor"
+require_relative "otp_rails/adapters/supervisor_adapter" # after supervisor: wraps a child Supervisor
+require_relative "otp_rails/dsl"
+require_relative "otp_rails/cli"

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: otp-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tim
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-09-13 00:00:00.000000000 Z
+dependencies: []
+description: A slim supervisor that starts, links, health-checks, and restarts the
+  processes of a Rails app (web, jobs, cable, cron) with OTP strategies.
+email:
+executables:
+- otp-rails
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/otp-rails
+- lib/otp_rails.rb
+- lib/otp_rails/adapter.rb
+- lib/otp_rails/adapters/command.rb
+- lib/otp_rails/adapters/puma.rb
+- lib/otp_rails/adapters/solid_queue.rb
+- lib/otp_rails/adapters/supervisor_adapter.rb
+- lib/otp_rails/backoff.rb
+- lib/otp_rails/child_spec.rb
+- lib/otp_rails/cli.rb
+- lib/otp_rails/dsl.rb
+- lib/otp_rails/heartbeat.rb
+- lib/otp_rails/orphan_guard.rb
+- lib/otp_rails/probe.rb
+- lib/otp_rails/restart_intensity.rb
+- lib/otp_rails/socket_server.rb
+- lib/otp_rails/strategy.rb
+- lib/otp_rails/supervisor.rb
+- lib/otp_rails/telemetry.rb
+- lib/otp_rails/version.rb
+homepage: https://github.com/shishi-odoshi/otp-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/shishi-odoshi/otp-rails
+  source_code_uri: https://github.com/shishi-odoshi/otp-rails
+  changelog_uri: https://github.com/shishi-odoshi/otp-rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/shishi-odoshi/otp-rails/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: OTP-style supervision trees for Rails processes
+test_files: []