quonfig 0.0.15 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4e037ad01a35ca5a3fb3ddcc30ad6b0dab78ad82e4908a4a8ce9e8bab6cab40
-  data.tar.gz: 8bcccb03befbab5f1fbed1cbae867ce970498ac0081c92e24db7d8eb899d2faa
+  metadata.gz: 68d9721e3220acc150e33b43e993c8b8b2380056453939b62b06b05cc4ef4255
+  data.tar.gz: 643c409f2b8fa3d5291d92fcf8a0d39cf5a2a67b4d697036497a19296f584d72
 SHA512:
-  metadata.gz: 9d4abdeaeaaad881e5f28cb9a653715dd8b1838ba33cc38b6b1f08db5f729173d5eadbf2afebfb6e3ca3a379f0354ab453fafd760a1fd61d13c3efef60ad0aee
-  data.tar.gz: 890131a3f75092f1b846ee4ca46c1dc20702b1effc3db5803443905d8a8571a33b672a691a18bbb0c3ad8471c5db72006a745f50ac0e919bf0997b49cf202045
+  metadata.gz: c133fdcdf47da1b026465f42dfc71e98be03590bb0df80ebd247a572bce6404a59b5f411b014e83349ca2278af2c4c62974c22c1ea9c0c7b1af474d933e91725
+  data.tar.gz: c982a887a21dcfe7545e2b50b71a09f2fb7465827819676a238bdbd87cbeaa7626f26e723eb3535c8e3f893de4f7bcebc93e31264783b76716add5057ece836c

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.0.17 - 2026-05-19
+
+- **Feat (datadir): opt-in `data_dir_auto_reload` (qfg-mol-2da).** Datadir mode previously loaded the workspace once at construction and served purely from memory. Set `data_dir_auto_reload: true` to have the SDK watch the configured `datadir`, re-read `Quonfig::Datadir.load_envelope`, and fire the existing `on_update` callback whenever files change. Adds `listen ~> 3.8` (FSEvents on macOS, inotify on Linux, polling fallback on Windows) as a runtime dep. Behavior: parse-then-swap (a failed parse keeps the previous envelope and skips the callback), debounced (`data_dir_auto_reload_debounce_ms`, default 200 ms — bursts coalesce to one reload), and gracefully downgrades when watch registration fails (read-only fs, immutable container, missing native backend). Symlinked datadirs are resolved to their real path before watching. Default is `false`; opt-in only.
+- **Feat (datadir + fork): auto-restart the watcher across `fork(2)` (qfg-mol-2da).** The watcher uses a background thread, which does not survive fork. The existing `Process._fork` hook (qfg-ryov, Ruby 3.1+) now also tears the datadir watcher down in the parent before fork and rebuilds a fresh one on the same `Client` in each child — no customer wiring required for Puma clustered mode, Unicorn, Sidekiq's parent-forks-workers model, Resque, or Spring. Ruby 3.0 customers continue to use the documented `Quonfig.fork` pattern in `on_worker_boot`, which rebuilds the watcher alongside the rest of the client.
+
+## 0.0.16 - 2026-05-15
+
+- **Feat (SSE): replace `ld-eventsource` with an SDK-owned reconnect loop (qfg-35sm).** sdk-ruby was the outlier among the four backend SDKs — sdk-go, sdk-node, and sdk-python all own their reconnect loop, only sdk-ruby handed it off to a library and scraped its log output to observe reconnects. The wire format we actually consume (plain JSON envelopes in single-line `data:` frames, no named events, no retry directives) is trivial enough that an SDK-owned loop is clearer than the library wrapper. New `Quonfig::SSEConfigClient` (~520 LoC, `lib/quonfig/sse_config_client.rb`) handles connect/parse/reconnect end-to-end. `restart_total` is now incremented at exactly one site under a mutex — verifiable, not log-scraped. `ld-eventsource` and the transitive `http` gem are removed from the gemspec. `ReconnectCountingLogger` and the `sse_reconnect_reset_interval` option (both 0.0.15-era defensive scaffolding around upstream behavior) are deleted — the bugs they defended against don't exist when the SDK owns the loop. Chaos: 10/10 in a 36-min run (scenarios 02 silent-stall, 05 sse-down-fallback, 09 flapping kill-storm).
+- **Fix (SSE): contain watchdog `Thread#raise` with `Thread.handle_interrupt` (qfg-tj18).** The new watchdog fires `Thread#raise(SSEReadDeadlineExceeded)` into the worker on a silent stall — the only reliable cross-platform way to unblock a Ruby thread blocked in `Net::HTTP`'s body-read on macOS. The decision to fire is mutex-guarded against `stop()`, but the raise itself is delivered at the worker's next interrupt checkpoint, which could be anywhere in the call stack. `run_loop`'s body now runs under `Thread.handle_interrupt(SSEReadDeadlineExceeded => :on_blocking)` so a late-landing raise can only land inside a blocking call; the `read_body` block explicitly switches to `:immediate`. A paranoid backstop `rescue` outside the until-`@stopped` loop ensures an escaped raise can never silently kill the worker.
+- **Fix (SSE): isolate `on_envelope` callback exceptions (qfg-m3lk).** A buggy user-supplied listener that raised during envelope delivery used to propagate out of `read_body`, get caught by `run_loop` as a transport error, bump `restart_total`, and reconnect — a perpetual reconnect storm at api-delivery-sse driven by a customer code bug. The callback is now wrapped in `begin/rescue StandardError` at the invocation site; exceptions are logged with class + message + backtrace sample and the stream continues uninterrupted. `Interrupt` and `SystemExit` are deliberately not caught so `Ctrl-C` still works.
+- **Fix (SSE): classify 401/403/404 as terminal errors (qfg-i5xv).** Non-200 responses used to be treated identically — `SSEHTTPStatusError` raised, `run_loop` rescued, `restart_total` bumped, backoff, retry, forever. For a bad SDK key (401) or revoked workspace (403) that was wasted load on api-delivery-sse with no recovery path short of a customer redeploy. New `SSEHTTPTerminalError` sentinel for 401/403/404; `run_loop` catches it, invokes `on_error`, exits the loop without bumping `restart_total`. Parent `Quonfig::Client` surfaces a terminal `:sse_terminal_failure` state distinct from transient `:error`. 429 and 5xx still retry.
+- **Feat (fork): install `Process._fork` hook so SSE auto-restarts after fork (qfg-ryov).** Ruby threads do not survive `fork(2)`. Customers initializing `Quonfig::Client` in the Puma master (the `preload_app! true` / Rails `config.eager_load = true` convention) used to silently lose SSE in every worker child. New `Quonfig::ForkSafety` module prepends `Process._fork` and fans out across all live `Quonfig::Client` instances (tracked in an `ObjectSpace::WeakMap`): in the parent before the syscall, threaded components (SSE worker, polling supervisor, telemetry reporter) are torn down; in the child after the syscall, they are rebuilt. `@stopped` is preserved so a `stop()`-ed client stays stopped across fork. Covers `Process.fork` / `Kernel#fork`; `Process.spawn` and `system("...")` exec a new program so in-process state doesn't apply. Ruby 3.0 lacks `Process._fork` and is documented as requiring manual `before_fork` / `on_worker_boot` wiring.
+
 ## 0.0.15 - 2026-05-15
 
 - **Fix (SSE): count ld-eventsource internal reconnects (qfg-ie49).** ld-eventsource auto-reconnects on a clean socket FIN *internally* and never fires `on_error`, so the qfg-ll6r on_error-based `restart_total` counter sat at 0 under flapping outages (chaos scenario 09 — proxy killed 5x in 30s). `restart_total` now counts actual reconnects from two mutually-exclusive sources: ld-eventsource internal reconnects (observed via a pass-through logger wrapper that watches the per-reconnect `"Will retry connection after"` info line — the only hook the library exposes) and SDK-driven reconnects in `@retry_thread`. `on_error` is no longer a counting source.

data/README.md

@@ -107,6 +107,107 @@ export QUONFIG_ENVIRONMENT=production
 client = Quonfig::Client.new  # reads QUONFIG_DIR + QUONFIG_ENVIRONMENT
 ```
 
+## Datadir mode: auto-reload on file changes
+
+In datadir mode the SDK loads the workspace once at construction time and then
+serves config purely from memory. Opt in to `data_dir_auto_reload: true` to
+have the SDK watch the directory and re-read the envelope whenever files
+change — an editor save, a `git pull`, or a build step that rewrites the
+workspace.
+
+```ruby
+client = Quonfig::Client.new(
+  datadir:              '/path/to/workspace',
+  environment:          'development',
+  data_dir_auto_reload: true # off by default — must be opted in
+)
+
+client.on_update do
+  puts 'Quonfig configs reloaded from disk'
+end
+
+# Edit a file under /path/to/workspace and on_update fires within ~200ms.
+
+# On shutdown, stop stops the watcher and cancels any pending debounce.
+client.stop
+```
+
+### When to enable
+
+- Local development with the datadir checked out from git.
+- Self-hosted servers that `git pull` the datadir on a schedule.
+- CI jobs that mutate the datadir between assertions.
+
+### When NOT to enable
+
+- **Read-only / immutable filesystems** (some containers, scratch images,
+  AWS Lambda). Watch registration may fail; the SDK degrades gracefully
+  (logs the error and continues serving the envelope it loaded at init time)
+  but you're paying for nothing.
+- **Build-time-embedded workflows** where the datadir is bundled into the
+  artifact and never changes at runtime. Watching wastes a thread and a
+  native-backend handle.
+- **Production paths where reload timing matters** — e.g. you'd rather pin
+  the envelope you shipped with and roll forward through a redeploy than
+  have it shift under traffic.
+
+Default is `false`; datadir mode is silent until you opt in.
+
+### Behavior contract
+
+- **Parse-then-swap.** If the new envelope fails to parse (truncated write,
+  mid-`git pull` state, invalid JSON), the SDK logs the error and **keeps
+  serving the previous envelope**. `on_update` is _not_ fired on parse
+  failure — only on a successful swap.
+- **Debounced.** Bursts of filesystem events (atomic-rename editor saves,
+  `git pull` touching dozens of files) coalesce into a single re-read.
+  Default window: **200ms** — long enough to absorb the 3–5 events a typical
+  editor emits in <50ms, short enough that interactive edits feel immediate.
+  Tune via `data_dir_auto_reload_debounce_ms` if you need a different
+  window.
+- **Graceful degrade.** If watch registration fails (read-only fs, immutable
+  container, missing native backend), the SDK logs and continues without
+  watching — it does **not** raise from the constructor.
+- **Symlinks.** The watcher resolves `datadir` to its real path at start
+  time. Editing the file the symlink points at _is_ detected; atomic flips
+  that retarget the link itself are **not**.
+- **Shutdown.** `client.stop` stops the watcher and cancels any pending
+  debounce. There is no separate handle to manage — the watcher lifecycle
+  is tied to the client.
+
+### Fork safety (Puma cluster, Unicorn, Resque, Sidekiq)
+
+The auto-reload watcher uses a background thread, which — like any Ruby
+thread — does not survive `fork(2)`. **You do not need to wire this up
+manually on Ruby 3.1+.** The SDK's `Process._fork` hook (see [Rails
+integration](#rails-integration) below) stops the watcher in the parent
+before fork and restarts a fresh watcher in each child after fork. This
+covers Puma clustered mode, Unicorn, Sidekiq's parent-forks-workers model,
+Resque, Spring, and manual `fork { ... }` calls.
+
+On Ruby 3.0 (no `Process._fork`), follow the manual `before_fork` /
+`on_worker_boot` pattern in the [Rails integration](#rails-integration)
+section — `Quonfig.fork` rebuilds the full client, including the datadir
+watcher, in the child.
+
+### Tuning the debounce window
+
+```ruby
+Quonfig::Client.new(
+  datadir:                          '/path/to/workspace',
+  data_dir_auto_reload:             true,
+  data_dir_auto_reload_debounce_ms: 1000 # wait a full second after the last event
+)
+```
+
+The default (200 ms) is tuned for interactive editing. Raise it if you have
+a noisy producer (continuously regenerating files) and you'd rather see one
+reload per second than per save. Lower it only if you've measured that 200 ms
+is meaningfully too slow for your use case.
+
+See the [open-source / local how-to](https://docs.quonfig.com/docs/how-tos/open-source-local)
+for the cross-SDK story (sdk-node, sdk-go, sdk-ruby, sdk-python, sdk-java).
+
 ## Environment variables
 
 | Variable                    | Purpose                                                                                  |
@@ -130,7 +231,9 @@ Quonfig::Client.new(
   on_no_default:   :error,
   global_context:  {},
   datadir:         '/path/to/workspace',
-  environment:     'production'
+  environment:     'production',
+  data_dir_auto_reload:             false,
+  data_dir_auto_reload_debounce_ms: 200
 )
 ```
 
@@ -147,6 +250,8 @@ Quonfig::Client.new(
 | `global_context`  | `Hash`                     | `{}`                                                                | Context applied to every evaluation.                                                              |
 | `datadir`         | `String`                   | `ENV['QUONFIG_DIR']`                                                | Path to a local workspace. When set, the SDK runs offline from disk.                              |
 | `environment`     | `String`                   | `ENV['QUONFIG_ENVIRONMENT']`                                        | Environment to evaluate in datadir mode. Required when `datadir` is set.                          |
+| `data_dir_auto_reload`              | `Boolean`         | `false`                                                             | Datadir mode only. When `true`, the SDK watches the datadir and re-reads the envelope when files change. See [Datadir mode: auto-reload on file changes](#datadir-mode-auto-reload-on-file-changes). |
+| `data_dir_auto_reload_debounce_ms`  | `Integer` (ms)    | `200`                                                               | Debounce window for the auto-reload watcher — events arriving inside the window are coalesced into a single re-read. Ignored when `data_dir_auto_reload` is `false`. |
 | `logger`          | Logger-like object         | `nil`                                                               | Optional host-app logger (e.g. `Rails.logger`). Must respond to `debug`/`info`/`warn`/`error`. When set, all SDK warnings/errors flow through this logger instead of the default stderr / SemanticLogger backend. |
 
 ## Typed getters
@@ -247,15 +352,41 @@ not want to inherit across a `fork(2)`. Forked threads in the child process
 are dead — the SSE socket is held open by a thread that no longer exists, and
 the child silently stops receiving live updates.
 
-Use `Quonfig::Client#fork` (or `Quonfig.fork` if you use the module-level
-singleton) in any process that fork-spawns workers. It returns a fresh client
-configured for the child: a new `ConfigStore`, a new SSE subscription, and
-suppressed telemetry double-counting (`Options#is_fork` is set to `true`).
+**On Ruby 3.1+ the SDK installs a `Process._fork` hook at load time** that
+automatically tears down threaded components in the parent and restarts them
+in the child. This covers any `Process.fork` / `Kernel#fork` path — Puma's
+clustered mode, Unicorn, Sidekiq's parent-forks-workers model, Spring, and
+manual `fork { ... }` calls. **No customer wiring is required.**
+
+Caveats:
+
+- Ruby 3.0 has no hookable choke point — fall back to manual wiring (below).
+- `system("fork-and-exec ...")` and `Process.spawn` are not covered (they do
+  not go through `Process._fork`), but those execute a new program, so the
+  in-process SSE state is moot.
+- The hook tears down the SSE/polling/telemetry threads in the parent before
+  fork (so the child does not inherit a live socket fd) and does **not**
+  auto-restart the parent. This mirrors the Puma master case: the master no
+  longer serves requests, so it does not need a live SSE connection. If you
+  have a non-Puma topology where the parent must keep streaming after fork,
+  call `Quonfig.instance.after_fork_in_child` manually in the parent after
+  the fork returns.
 
 ### Puma (clustered mode)
 
+With the automatic fork hook, the typical Puma config needs **no Quonfig
+lifecycle wiring** — initialize in your Rails initializer and let the hook
+handle the rest:
+
+```ruby
+# config/initializers/quonfig.rb
+Quonfig.init(Quonfig::Options.new(sdk_key: ENV.fetch('QUONFIG_BACKEND_SDK_KEY')))
+```
+
+If you're on Ruby 3.0 (no `Process._fork`), wire the legacy hooks manually:
+
 ```ruby
-# config/puma.rb
+# config/puma.rb (Ruby 3.0 only)
 before_fork do
   Quonfig.instance.stop          # close the master's SSE before forking
 end
@@ -265,18 +396,18 @@ on_worker_boot do
 end
 ```
 
-If you initialize Quonfig lazily (in a Rails initializer) and run Puma in
-single mode (no clustering), no fork hook is needed.
-
 ### Sidekiq
 
-Sidekiq's parent process forks workers. Wire the same lifecycle:
+On Ruby 3.1+ the automatic fork hook covers Sidekiq workers too — no
+`configure_server` wiring required.
+
+On Ruby 3.0:
 
 ```ruby
 # config/initializers/quonfig.rb
 Quonfig.init(Quonfig::Options.new(sdk_key: ENV.fetch('QUONFIG_BACKEND_SDK_KEY')))
 
-# config/initializers/sidekiq.rb
+# config/initializers/sidekiq.rb (Ruby 3.0 only)
 Sidekiq.configure_server do |config|
   config.on(:startup)  { Quonfig.fork if Process.ppid != 1 }
   config.on(:shutdown) { Quonfig.instance.stop rescue nil }
@@ -284,7 +415,7 @@ end
 ```
 
 For Sidekiq web/CLI processes that don't fork (default `concurrency: 1`),
-`Quonfig.init` in the initializer is sufficient.
+`Quonfig.init` in the initializer is sufficient on any Ruby version.
 
 ### Spring / Bootsnap preloaders
 

data/lib/quonfig/client.rb

@@ -20,6 +20,29 @@ module Quonfig
   class Client
     LOG = Quonfig::InternalLogger.new(self)
 
+    # qfg-ryov: instance registry for the Process._fork hook. Every live
+    # Client is tracked here so the hook can fan out before_fork_in_parent /
+    # after_fork_in_child across all of them without the customer needing to
+    # name a specific instance. ObjectSpace::WeakMap means a Client that goes
+    # out of scope is GC'd without leaking through this registry. Stopped
+    # Clients stay in the registry until GC; both fork hooks early-return on
+    # +@stopped+ so a stopped instance is effectively a no-op. (We don't use
+    # WeakMap#delete because it was added in Ruby 3.3 and the matrix still
+    # includes 3.2.)
+    @instances = ObjectSpace::WeakMap.new
+    @instances_mutex = Mutex.new
+
+    class << self
+      # Iterate live Client instances. Used by Quonfig::ForkSafety.
+      def each_instance(&block)
+        @instances_mutex.synchronize { @instances.keys }.each(&block)
+      end
+
+      def register_instance(client)
+        @instances_mutex.synchronize { @instances[client] = true }
+      end
+    end
+
     attr_reader :options, :resolver, :store, :evaluator, :instance_hash,
                 :config_loader, :telemetry_reporter
 
@@ -48,17 +71,23 @@ module Quonfig
       @sse_state = :idle
       @sse_ever_connected = false
       @fallback_engage_timer = nil
+      @sse_terminal_failure = false
 
       # If the caller injected a store, we're in test/bootstrap mode; skip I/O.
       return if store
 
       if @options.datadir
         load_datadir_into_store
+        start_datadir_watcher if @options.data_dir_auto_reload
       else
         initialize_network_mode
       end
 
       initialize_telemetry
+
+      # Register only for non-store-injected clients (a caller-supplied store
+      # is the test/bootstrap path; the fork hook does not apply there).
+      self.class.register_instance(self) unless store
     end
 
     # ---- Lookup --------------------------------------------------------
@@ -264,34 +293,57 @@ module Quonfig
 
     def stop
       @stopped = true
-      begin
-        @sse_client&.close
-      rescue StandardError => e
-        LOG.debug "Error closing SSE client: #{e.message}"
-      end
-      @sse_client = nil
+      tear_down_threaded_components!
+    end
 
-      cancel_fallback_engage_timer
+    # qfg-ryov: pre-fork hook. Close the SSE worker, polling supervisor,
+    # telemetry reporter, and any fallback-engage timer. Idempotent — calling
+    # twice is safe. Does NOT set @stopped: the client is still expected to
+    # be usable post-fork via after_fork_in_child.
+    #
+    # Why this matters: Ruby threads do not survive fork(2). If we let the
+    # child inherit a live Net::HTTP socket, both processes read from the
+    # same fd and corrupt each other's bytes. Closing in the parent before
+    # fork is the only safe shape.
+    def before_fork_in_parent
+      return if @stopped
 
-      begin
-        @poll_supervisor&.stop
-      rescue StandardError => e
-        LOG.debug "Error stopping poll supervisor: #{e.message}"
+      tear_down_threaded_components!
+    end
+
+    # qfg-ryov: post-fork (in child) hook. Re-establish whatever threaded
+    # components the client had pre-fork. No-op if the client was already
+    # stopped (the customer asked for it to be dead — do not resurrect),
+    # or if the client is in datadir mode (no threaded components to start).
+    def after_fork_in_child
+      return if @stopped
+
+      if @options.datadir
+        start_datadir_watcher if @options.data_dir_auto_reload
+        return
       end
-      @poll_supervisor = nil
 
-      begin
-        @telemetry_reporter&.stop
-      rescue StandardError => e
-        LOG.debug "Error stopping telemetry reporter: #{e.message}"
+      return if @config_loader.nil? # never finished network init (e.g. invalid key)
+
+      # SSE state machine carries flags that no longer apply in the child
+      # (the parent had connected, the parent had errored, etc.). Reset.
+      @state_mutex.synchronize do
+        @sse_state = :idle
+        @sse_ever_connected = false
+        @sse_terminal_failure = false
       end
-      @telemetry_reporter = nil
+
+      sse_started = @options.enable_sse && start_sse
+      start_polling if @options.enable_polling && !sse_started
+
+      restart_telemetry_in_child
     end
 
     # quonfig_sdk_worker_restart_total counter (Tier 1 supervisor contract).
     # Layer 1 (SSE) is tracked on Quonfig::SSEConfigClient#restart_total —
-    # incremented on every on_error edge from ld-eventsource (qfg-ll6r).
-    # Layer 2 (HTTP polling fallback) is wired through Quonfig::WorkerSupervisor.
+    # incremented once per reconnect attempt by the SDK-owned reconnect
+    # loop (qfg-35sm). Layer 2 (HTTP polling fallback) is wired through
+    # Quonfig::WorkerSupervisor.
     #
     # Pass +layer:+ ('1' or '2') to read a single layer; default returns the
     # sum across both layers so the chaos harness (and operators) can pull
@@ -357,6 +409,48 @@ module Quonfig
 
     private
 
+    # Close every threaded component and drop its reference. Used by both
+    # +stop+ (where @stopped is also flipped) and +before_fork_in_parent+
+    # (where @stopped is left alone so the child can restart).
+    def tear_down_threaded_components!
+      begin
+        @sse_client&.close
+      rescue StandardError => e
+        LOG.debug "Error closing SSE client: #{e.message}"
+      end
+      @sse_client = nil
+
+      cancel_fallback_engage_timer
+
+      begin
+        @poll_supervisor&.stop
+      rescue StandardError => e
+        LOG.debug "Error stopping poll supervisor: #{e.message}"
+      end
+      @poll_supervisor = nil
+
+      begin
+        @telemetry_reporter&.stop
+      rescue StandardError => e
+        LOG.debug "Error stopping telemetry reporter: #{e.message}"
+      end
+      @telemetry_reporter = nil
+
+      begin
+        @datadir_watcher&.stop
+      rescue StandardError => e
+        LOG.debug "Error stopping datadir watcher: #{e.message}"
+      end
+      @datadir_watcher = nil
+    end
+
+    # Rebuild the telemetry reporter in the child after fork. Mirrors the
+    # original initialize_telemetry path — fresh aggregators, fresh reporter.
+    def restart_telemetry_in_child
+      @telemetry_reporter = nil
+      initialize_telemetry
+    end
+
     # Stamp +last_successful_refresh+ at install time. Called by every code
     # path that hands an envelope to the cache: datadir load, initial HTTP
     # fetch, SSE event apply, and polling worker fetch.
@@ -402,20 +496,31 @@ module Quonfig
       @sse_error_callback ||= ->(error) { handle_sse_error(error) }
     end
 
-    def handle_sse_error(_error)
+    def handle_sse_error(error)
+      # qfg-i5xv: classify terminal HTTP failures (401/403/404). The same SDK
+      # key that won't auth over SSE won't auth over HTTP polling either, so
+      # we must NOT engage the Layer 2 fallback — that just moves the
+      # auth-failure storm from one endpoint to another. Once flipped,
+      # @sse_terminal_failure latches: a buggy customer retry loop cannot
+      # un-classify the failure by driving the state machine.
+      @state_mutex.synchronize { @sse_terminal_failure = true } if error.is_a?(Quonfig::SSEConfigClient::SSEHTTPTerminalError)
       handle_sse_state_change(:error)
     end
 
     def handle_sse_state_change(new_state)
       state = new_state.to_sym
-      ever_connected = @state_mutex.synchronize do
+      ever_connected, terminal = @state_mutex.synchronize do
         @sse_state = state
         @sse_ever_connected = true if state == :connected
-        @sse_ever_connected
+        [@sse_ever_connected, @sse_terminal_failure]
       end
 
       return unless @options.respond_to?(:enable_polling) && @options.enable_polling
       return if @stopped
+      # qfg-i5xv: a terminal SSE classification suppresses polling engage in
+      # every branch — the customer's key is bad and HTTP polling will fail
+      # identically. Operators surface this via #terminal_failure?.
+      return if terminal
 
       case state
       when :connected
@@ -430,6 +535,21 @@ module Quonfig
       end
     end
 
+    public
+
+    # qfg-i5xv: true once the SSE layer has classified an HTTP response as
+    # terminal (401/403/404) — bad SDK key, revoked workspace permission,
+    # or wrong endpoint. The classification latches: the SDK will not
+    # auto-recover, and a customer-supplied retry must rebuild the client.
+    # Surfaced for operator alerting; `connection_state` still reports
+    # `:disconnected` to honor the documented connection_state vocabulary
+    # (supervisor-test-contract.md §"connectionState()" — values fixed).
+    def terminal_failure?
+      @state_mutex.synchronize { @sse_terminal_failure }
+    end
+
+    private
+
     def cancel_fallback_engage_timer
       timer = @state_mutex.synchronize do
         t = @fallback_engage_timer
@@ -568,10 +688,60 @@ module Quonfig
 
     def load_datadir_into_store
       envelope = Quonfig::Datadir.load_envelope(@options.datadir, @options.environment)
+      apply_datadir_envelope(envelope)
+    end
+
+    # Apply a freshly loaded datadir envelope to the store. Keys that were
+    # present before but missing now are deleted, so a `rm configs/foo.json`
+    # propagates through the auto-reload path. Records a refresh timestamp.
+    # Caller is responsible for firing on_update.
+    def apply_datadir_envelope(envelope)
+      new_keys = envelope.configs.map { |cfg| cfg['key'] }.compact.to_set
+      old_keys = @store.keys.to_set
+      (old_keys - new_keys).each { |k| @store.delete(k) }
       envelope.configs.each { |cfg| @store.set(cfg['key'], cfg) }
       record_refresh!
     end
 
+    # qfg-mol-2da: start the filesystem watcher for datadir auto-reload.
+    # On listen-registration failure (read-only fs, missing native backend),
+    # log and continue without watching — the SDK keeps serving the envelope
+    # captured at init.
+    def start_datadir_watcher
+      return unless @options.datadir
+
+      watcher = Quonfig::DatadirWatcher.new(
+        datadir: @options.datadir,
+        debounce_ms: @options.data_dir_auto_reload_debounce_ms,
+        on_change: -> { reload_datadir! },
+        on_error: ->(err) { LOG.warn "[quonfig] datadir watcher error: #{err.class}: #{err.message}" }
+      )
+      unless watcher.start
+        LOG.warn '[quonfig] data_dir_auto_reload requested but watcher registration failed; continuing without auto-reload'
+        return
+      end
+      @datadir_watcher = watcher
+    end
+
+    # Re-read the datadir into a fresh envelope and atomically install it.
+    # Parse errors (mid-write JSON, garbage file) are logged and swallowed:
+    # the previous envelope stays in the store and on_update does NOT fire.
+    # qfg-mol-2da.
+    def reload_datadir!
+      return if @stopped
+      return unless @options.datadir
+
+      begin
+        envelope = Quonfig::Datadir.load_envelope(@options.datadir, @options.environment)
+      rescue StandardError => e
+        LOG.warn "[quonfig] datadir reload failed; keeping previous envelope: #{e.class}: #{e.message}"
+        return
+      end
+
+      apply_datadir_envelope(envelope)
+      notify_on_update_callback
+    end
+
     # Initialize network mode: sync HTTP fetch (bounded by
     # initialization_timeout_sec) then start SSE + polling as requested.
     def initialize_network_mode
@@ -904,4 +1074,42 @@ module Quonfig
       end
     end
   end
+
+  # qfg-ryov: hook into Process._fork so customers using Puma's clustered
+  # mode (or any preload/fork-worker server) don't have to wire
+  # +before_fork+/+on_worker_boot+ manually. Ruby 3.1+ routes every
+  # +Kernel#fork+/+Process.fork+ call through +Process._fork+, so a single
+  # prepend covers them all.
+  #
+  # Process._fork's contract:
+  #   - Called in the parent process before the fork syscall.
+  #   - Returns 0 in the child, child's pid in the parent.
+  #   - +super+ performs the actual fork.
+  #
+  # The parent's view: SSE/polling/telemetry threads are torn down before
+  # the syscall so the child does not inherit a live Net::HTTP socket fd
+  # (which would corrupt both sides). The parent does NOT auto-restart —
+  # that mirrors the Puma master use case where the master process no
+  # longer serves requests after spawning workers.
+  module ForkSafety
+    def _fork
+      Quonfig::Client.each_instance(&:before_fork_in_parent)
+      pid = super
+      Quonfig::Client.each_instance(&:after_fork_in_child) if pid.zero?
+      pid
+    rescue StandardError => e
+      # Fork-hook failures must never break the customer's fork. Worst case
+      # the child inherits dead SSE threads (the pre-qfg-ryov behavior) —
+      # bad, but recoverable. Crashing the fork itself is not.
+      Quonfig::Client::LOG.error "Quonfig fork hook error: #{e.class}: #{e.message}"
+      raise if pid.nil? # super never returned — propagate fork failures
+
+      pid
+    end
+  end
+
+  # Ruby 3.0 lacks Process._fork. There's no hookable choke point on 3.0, so
+  # customers must keep wiring their own Puma before_fork / on_worker_boot
+  # (see README "Rails integration"). On 3.1+ we install the hook globally.
+  Process.singleton_class.prepend(ForkSafety) if Process.respond_to?(:_fork)
 end