quonfig 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8408e71b66de6bfe3e771b4091429d31f15f1dbdc0bb74d2e05bc3bcd83415db
-  data.tar.gz: e22b82909ffbb87dec181aa5c526ae12f7d4d7669c498027809ba8209ccd7c97
+  metadata.gz: 5e8807ad54199b5ee24245cdf140a72aed0644e712308d867457d729df1bb122
+  data.tar.gz: 20b1d12fb441394f4d31198854b55dd90f78c925115982a32548415993c77958
 SHA512:
-  metadata.gz: '0149ee240869602465f2ff10180f8f2c35b577bf12d6f73bf33afe02ac16e0742e93744c085cbd641c1640b542a137dbde8650e5dde580174b718d89d4b08ed6'
-  data.tar.gz: b223c20dc4cde206a30e803d43d507c1e4b5f204465c7e5e0c1f19db178842bc3a5013db7d734d09178a23cddca3df4e2b275f4f000b71bb3f2566e6395d337d
+  metadata.gz: cda8d4a8d332710a58f3be0e1e068e767858c9806f199bc23a5a2f010e7540d4fd9a159b20ac23f9d34f1a7f60b5aac10fcffdeda030356ace8536779048126a
+  data.tar.gz: 33dcc1b5201298630936e743f5e44b188393b810ee94287623dce7598b98ab68ee0a2eb8bddb70f92da2fb3419f6a0b7f2a3081e2510b7f2d144087765b541b6

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.4.0 - 2026-09-10
+
+> **If you fork worker processes and keep evaluating in the parent, upgrade.** On 1.0.0–1.3.0 the parent process went permanently dark after any `fork(2)` — it kept serving whatever config snapshot it held at the moment of the fork, forever, while `connection_state` reported `:connected`.
+
+- **Fix (fork): the `Process._fork` hook is now child-only — the parent is never touched (qfg-lv4n.1).** Since 0.0.16 the hook tore the SSE worker, fallback poller, telemetry reporter, and datadir watcher down **in the parent** before the fork syscall, and restarted them only in the child. Any topology where the parent keeps evaluating after a fork — a Sidekiq process using the `parallel` gem, a `fork { ... }` inside a job, a rake task that forks — lost live updates permanently. A customer's Sidekiq process served a 13-day-old snapshot through four rollout changes this way. The hook now does **nothing** on the parent side: the parent keeps its stream, its poller, its telemetry reporter, and its live config straight through any number of forks. This restores the design every other SDK in this space uses (Reforge's `Reforge.fork`, LaunchDarkly's `postfork`, dd-trace-rb / redis-client / connection_pool, which all branch on the child stage of `_fork` only). No customer wiring is required, and no public API was removed.
+- **Change (fork): a forked child re-initializes on its FIRST use of the client, and never inherits the parent's config snapshot.** The hook does no I/O at all: it drops what the child inherited — including the parent's store — and arms a flag. The first `get` / `defined?` / `keys` / details lookup in the child then does exactly what `Client.new` does: its own blocking config fetch under the configured `init_timeout_ms` and `on_init_failure`, then its own SSE stream (or fallback poller) and its own telemetry reporter. Three consequences worth knowing: the first call in a forked child pays one fetch; a child that never uses the client costs nothing (no fetch, no socket, no thread, and `stop` returns immediately); and because the child's store starts empty, its first envelope is *installed* rather than dropped by the reject-older guard as same-generation. This is full parity with Reforge, where a forked process simply builds a new client. `connection_state` does not trigger the re-initialization — a diagnostic must never open a socket — and answers `:initializing` while one is pending.
+- **Fix (fork): concurrent first use in a child waits for the one rebuild (qfg-lv4n.1).** The re-initialization used an unlocked fast path and cleared its pending flag *before* doing the work, so only the thread that won the mutex actually blocked: every other thread read the cleared flag, skipped the mutex, and evaluated against the brand-new **empty** store. Sixteen threads hitting a freshly forked client against a 400ms config endpoint returned `{nil=>15, "v1"=>1}`. The flag now stays set for the whole rebuild, so every other caller blocks on it and then sees the fetched config — one fetch, one stream dial, one reporter per child, however many threads race the first request. A same-thread guard keeps a customer logger (a `semantic_logger_filter` / `stdlib_formatter` that evaluates a config) from deadlocking on the non-reentrant lock if it fires from inside the rebuild.
+- **Fix (fork): a hard timeout mid-rebuild no longer leaves the child dark forever (qfg-lv4n.1).** `Timeout::ExitException` (Ruby 3.3's `timeout` 0.4.1), rack-timeout's `RequestTimeoutException`, and `Thread#kill` are all `Exception`, not `StandardError`, so they crossed the rebuild's rescue untouched — and with the pending flag already cleared, every later call in that child returned `nil` over an empty store with no stream, no poller and no reporter, permanently. The flag is now cleared at the point the child actually has a live path to config, so anything that escapes before that leaves the rebuild armed and the next call retries it.
+- **Fix (fork): `stop` racing an in-flight rebuild no longer orphans an SSE worker (qfg-lv4n.1).** `stop` cleared the pending flag and tore down without taking the rebuild lock, so a rebuild already past that point went on to build a stream nothing held a reference to and nothing could close. `stop` now raises its stopped flag **before** queueing for the rebuild lock — an in-flight rebuild sees it and starts neither an update channel nor a telemetry reporter — and the teardown itself runs under that lock, so it can never interleave with construction.
+- **Fix (fork): a datadir child whose rebuild fails no longer dials SSE (qfg-lv4n.1).** The failure path started the update channel regardless of mode, so a child of a purely **offline** (datadir) client opened a stream to `stream.primary.quonfig.com` on its first lookup and then logged ``Error applying SSE envelope: undefined method `apply_envelope' for nil`` for every envelope that arrived — with nothing re-armed, repairing the workspace on disk never helped. A datadir client's healing path is the filesystem: the failure path now starts the datadir watcher when `data_dir_auto_reload` is on, and otherwise re-arms the rebuild so the next use retries the load.
+- **Fix (fork): `after_fork_in_child` called in the PARENT is now a no-op (qfg-lv4n.1).** Releases 1.0.0–1.3.0 documented calling `Quonfig.instance.after_fork_in_child` in the parent after `fork` returned as the workaround for the parent going dark. On 1.4.0 the parent's components are alive, so each such call orphaned a live SSE worker and its stream, zeroed the store, and stopped the **owner's** telemetry reporter — three calls took a process from 2 worker threads and 1 live stream to 8 and 4, and the orphans outlived `stop`. The hook now early-returns (one debug line) in the process that **owns** the client, decided by comparing the current pid against the one stamped when the client was built. **If you added that call in the parent as a 1.3.0 workaround, remove it; it does nothing there now.**
+- **Fix (fork): a child forked from inside an `on_update` callback rebuilds like any other child (qfg-lv4n.1).** Parent-vs-child detection asked whether the inherited SSE worker thread was alive. `on_update` runs *on* that worker thread, so a customer who forks from the callback forks on it — making it the child's one surviving thread, and making the inherited `@worker.alive?` answer **true in a real child**. Such a child was classified as the parent: the hook ignored it, it served the parent's snapshot for the rest of its life, reported `:connected`, and resumed the parent's SSE loop on the shared file descriptor. Ownership is now a pid stamp taken at construction (and re-taken when a child rebuilds), so a pid mismatch is proof of a fork child whatever the inherited `Thread` objects claim. The same stamp closes the other end of the hole: a parent-side `after_fork_in_child` on a client with no threads at all (datadir + `data_dir_auto_reload: false` + no SDK key) sailed straight past the old liveness guard and wiped the live store; it is now correctly a no-op.
+- **Fix (fork): a retried rebuild no longer dials a second stream (qfg-lv4n.1).** The rebuild disarms its pending flag only *after* the update channel is up, so a non-`StandardError` landing in that window (rack-timeout, `Timeout::ExitException`, `Thread#kill`) left the flag armed **with a live stream**. The retry re-ran network init, opened a second SSE stream, and overwrote `@sse_client` — orphaning the first worker where `stop` could never reach it, and leaving the child holding two streams against the delivery service. `start_update_channel` is now idempotent: it returns immediately if an SSE worker or poll supervisor is already alive.
+- **Fix (fork): `on_init_failure: :raise` behaves the same in a forked child as in a fresh client (qfg-lv4n.1).** A failed re-initialization was always swallowed and logged, so the documented "exactly like a newly constructed client" was false for the one option whose entire job is raise-vs-return. Under `:raise` the first use in a child now raises the init error out of the lookup — Reforge does the same, raising the init error out of `get` itself — and later lookups keep raising, without re-fetching, until the update channel lands an envelope. The update channel is still started on the way out so the child can heal. **Note that `:raise` is the default**, so with default options a forked child whose first lookup lands in a total delivery outage (primary and secondary both unreachable) raises where 1.3.0 silently served the parent's snapshot; set `on_init_failure: :return` if you would rather a child serve defaults through an outage. `:return` is unchanged: one line logged, defaults served.
+- **Fix (fork): `Quonfig.fork` / `Client#fork` in a child the hook already prepared returns the same client (qfg-4t5o).** The 1.0–1.3 README taught `on_worker_boot { Quonfig.fork }`, and on Ruby 3.1+ that call ran *after* the `Process._fork` hook had already prepared the client in the worker. Before first use it discarded the prepared client and built a second one with an eager fetch; after first use it left the worker holding two live SSE streams and two telemetry reporters, the first pair orphaned where `stop` could never reach them. `Client#fork` now returns `self` when the hook has already prepared it in the current process, so a leftover call from older docs is harmless. Outside a hook-prepared child (the owning process, Ruby 3.0, a client stopped before the fork) it still builds a fresh client, which is the Ruby 3.0 manual-wiring path; the old client is never stopped.
+- **Fix (fork): the public `store` / `resolver` / `evaluator` / `config_loader` readers route through the post-fork re-initialization (qfg-lv4n.1).** They bypassed it entirely, so in a forked child that had not been used yet `client.store.get(key)` answered `nil` and `client.resolver.get(key, {})` raised `MissingDefaultError` against the empty store. They stay public (semver) and now re-initialize before handing the component back; reading one in a forked child can therefore block on the child's own fetch.
+- **Fix (fork): the child drops inherited references instead of closing them.** `fork(2)` duplicates file descriptors, so the child's copy of the SSE socket points at the connection the **parent** is still streaming on — closing it would write a TLS `close_notify` onto that shared connection and kill the parent's stream. The child now nils `@sse_client`, `@poll_supervisor`, `@telemetry_reporter`, `@datadir_watcher`, and the pending fallback-engage timer without calling `close` / `stop` / `join` on any of them (joining an inherited thread blocks forever, since the thread does not exist in the child), then builds everything fresh.
+- **Fix (fork): the child's telemetry starts empty.** The forked child gets brand-new context-shape, example-context, evaluation-summary, and failover aggregators rather than inheriting the parent's half-full ones (the reporter is not *started* until the child's first use). The parent flushes the data it collected; the child reports only its own, so a fork no longer double-counts a window of evaluations.
+- **Fix (fork/telemetry): the inherited `at_exit` drain no longer speaks for the parent.** `TelemetryReporter#start` registers a process-wide `Kernel.at_exit` closure over the reporter; `fork(2)` copies it, and dropping the client's reference in the child does not unregister it — so any child that exited the normal way (block-form `fork` + `exit`, which is what the `parallel` gem does) POSTed a full copy of the **parent's** un-flushed window under the parent's `instanceHash`, and the parent then POSTed it again. The reporter now records an owner pid on `start`, and `sync`, `stop`, and the `at_exit` drain are no-ops (one debug line) in any other process; the child additionally discards the inherited aggregators. Measured on a three-child `Parallel.map`: 404 evaluations reported for 101 performed, now 101. Nothing is closed, stopped, or joined — the thread does not exist in the child and the HTTP connection's fd is shared with the parent.
+- **Fix (fork): one client failing to rebuild no longer takes the rest of the registry down with it.** The child-side fan-out was covered by a single hook-wide rescue, so the first `after_fork_in_child` to raise (thread exhaustion, a customer logger that raises) aborted the loop and every client behind it in the registry stayed dark. Each instance now has its own rescue and the fan-out continues, logging the failure at error.
+- **Fix (fork): a forked datadir child gets its own telemetry reporter (qfg-vquv).** The datadir branch of `after_fork_in_child` returned before the aggregator/reporter rebuild, so a datadir + SDK-key child — an emitting combination since 1.3.0 — recorded nothing of its own for the rest of its life. It now rebuilds aggregators and reporter under exactly the SDK-key gating a fresh client applies.
+- **Fix (diagnostics): `connection_state` derives from liveness, not from a stored flag.** It previously answered `:connected` off `@sse_state` alone, which the teardown path never reset — so a client with no SSE worker and no poller alive still reported healthy. That is why the incident above stayed invisible for 13 days. A network client that is supposed to hold an SSE stream and has no live worker now reports `:disconnected`. The documented value set (`:initializing`, `:connected`, `:disconnected`, `:falling_back`) is unchanged, and `:connected` still covers datadir mode and post-fetch clients with SSE disabled.
+- **Deprecated: `Client#before_fork_in_parent`.** Still public and still works, but the fork hook no longer calls it. There is no longer any reason to tear a parent down before forking; call `stop` if you want a client dead. Slated for removal in 2.0.0.
+- **Docs:** "one telemetry POST at exit" for a per-job forking worker is now qualified — the at-exit drain only happens when the child exits *normally*. `Parallel` children do; **Resque children call `exit!` by default**, which skips every `at_exit` handler, so there is no drain and no telemetry POST unless `RUN_AT_EXIT_HOOKS=1` is set.
+- **Docs:** the README's fork section previously claimed the SDK covered "Sidekiq's parent-forks-workers model" (Sidekiq OSS does not fork — it runs jobs on threads) and documented "does not auto-restart the parent" as intentional. Both are corrected. The Puma snippet no longer suggests `before_fork { Quonfig.instance.stop }`, and the cases that actually fork inside Sidekiq (the `parallel` gem, an explicit `fork { }`, Enterprise swarm) are named as covered. The Ruby 3.0 `parallel` snippet no longer calls `Quonfig.fork` once per row (that builds a client per item; it is now a pid-memoized rebuild once per child process, with a note that 3.0 is EOL), and the Puma/Unicorn worker-boot snippets show `SemanticLogger.reopen` alone on 3.1+ — calling `Quonfig.fork` there after the hook has already rebuilt leaves the worker with two live SSE streams and two reporters.
+
 ## 1.3.0 - 2026-08-18
 
 > **Heads up — datadir users will start emitting telemetry.** Datadir mode with a valid SDK key now emits usage telemetry as documented; it previously sent nothing. If you run the SDK with a `datadir:` (or `QUONFIG_DIR`) **and** an SDK key, upgrading to 1.3.0 means evaluation summaries and context telemetry begin flowing to the telemetry service from that deployment — data you were not sending on 1.2.0. Disable with the standard telemetry options if unwanted (`collect_evaluation_summaries: false` and `context_upload_mode: :none`). A datadir client with **no** SDK key still sends nothing at all.

data/README.md

@@ -210,16 +210,16 @@ Default is `false`; datadir mode is silent until you opt in.
 
 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.
+manually on Ruby 3.1+.** After a fork, the child re-loads the workspace from
+disk and registers a fresh watcher on its first use of the client (see [Rails
+integration](#rails-integration) below); a child that never uses the client
+starts no watcher at all. The parent's watcher is left alone and keeps
+working. This covers Puma clustered mode, Unicorn, Resque, Spring, and manual
+`fork { ... }` calls — including a `fork` inside a Sidekiq job.
 
-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.
+On Ruby 3.0 (no `Process._fork`), follow the manual `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
 
@@ -414,16 +414,41 @@ If both are supplied, the explicit `logger_name:` wins.
 
 ## Rails integration
 
-The SDK runs a background SSE thread (and optional polling thread) that you do
-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.
+The SDK runs a background SSE thread (and optional polling thread). Ruby
+threads do not survive `fork(2)`, so a child process inherits references to
+threads that no longer exist and silently stops receiving live updates.
 
 **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.**
+handles this for you. It covers any `Process.fork` / `Kernel#fork` path —
+Puma's clustered mode, Unicorn, Spring, Resque, a `fork { ... }` inside a
+Sidekiq job, and the `parallel` gem. **No customer wiring is required.**
+
+**The hook is child-only. A fork never touches the process that forked.**
+The parent keeps its SSE stream, its poller, its telemetry reporter, and its
+live config straight through any number of forks — so a long-lived process
+that forks workers *and keeps evaluating* (a Sidekiq process using the
+`parallel` gem, a rake task that calls `fork`) stays current.
+In the child, the SDK drops the inherited references without touching the
+objects — it never closes the inherited socket, because `fork(2)` duplicates
+the file descriptor and closing the child's copy of a TLS connection would
+tear down the stream the **parent** is still using.
+
+> **Upgrading from 1.3.0 or earlier:** if you added a manual
+> `Quonfig.instance.after_fork_in_child` call **in the parent** as a
+> workaround for the parent going dark, remove it. As of 1.4.0 that call is a
+> no-op in the process that owns the client — the SDK decides that by
+> comparing the current pid against the one it stamped when the client was
+> built, so it is exact whether or not the parent has any threads running. It
+> will not hurt you, but it is no longer doing anything, and the parent needs
+> no call.
+
+**After a fork, the child re-initializes on its first use of the client,
+exactly like a newly constructed client — including its `on_init_failure`
+policy: it fetches its own config and starts its own threads. It does not
+evaluate from the parent's snapshot.** The hook itself does no I/O — it drops
+what the child inherited and arms the re-initialization. So the first call in
+a forked child pays one fetch, and a child that never uses the client costs
+nothing: no fetch, no stream, no thread, no telemetry.
 
 Caveats:
 
@@ -431,13 +456,44 @@ Caveats:
 - `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.
+- The first lookup in a forked child **blocks** on that child's own config
+  fetch, under the same `init_timeout_ms` and `on_init_failure` options a
+  fresh client uses. **The default is `on_init_failure: :raise`**, so if the
+  child's fetch fails against every `api_urls` leg (primary and secondary
+  both unreachable) the failure **raises out of that first lookup**, exactly
+  as `Client.new` would at boot, and later lookups keep raising — without
+  re-fetching — until the update channel lands an envelope, at which point
+  the client serves config normally again. On 1.3.0 and earlier a child in
+  that situation silently served the parent's snapshot instead. If you would
+  rather a forked child serve defaults through an outage, set
+  `on_init_failure: :return`: a failed fetch then logs one line and the child
+  serves defaults until its stream or poller lands the first envelope.
+- **Other threads wait.** Every thread that reaches the client while that
+  first fetch is in flight blocks on it and then sees the fetched config. One
+  fetch, one stream dial, and one telemetry reporter per child, however many
+  threads race the first request.
+- **`connection_state` never triggers the re-initialization** — a diagnostic
+  must not open a socket. A child that has not used the client yet answers
+  `:initializing`, which is exactly what it is; it flips to `:connected` on
+  first use.
+- The child's telemetry aggregators start empty. The parent flushes the data
+  it collected before the fork; the child reports only its own.
+- **Per-job forking pays per job.** A Resque-style worker that forks a child
+  per job (or `Parallel.map` with one row per process) pays, in each child
+  that touches the client, one config fetch, one SSE dial, and — **when the
+  child exits normally** — one telemetry POST at exit. That is the price of
+  the child holding its own current config and its own telemetry window, and
+  it is deliberate — the delivery service counts each of those connections as
+  a real client. A child that never uses the client pays none of it.
+
+  The at-exit drain depends on the child running `at_exit` handlers at all.
+  `Parallel` children do. **Resque children call `exit!` by default**, which
+  skips every `at_exit` handler — so there is no drain and no telemetry POST
+  unless you set `RUN_AT_EXIT_HOOKS=1`. Nothing else about the child changes;
+  it just never flushes the evaluations it collected.
+- In datadir mode a child whose workspace fails to load never dials the
+  network: it logs the failure and, if `data_dir_auto_reload` is on, watches
+  for a repaired workspace; otherwise the next use retries the load.
 
 ### Puma (clustered mode)
 
@@ -450,52 +506,72 @@ handle the rest:
 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:
+If you use SemanticLogger you still need to reopen it in each worker — but
+`Quonfig.fork` is not needed in that block on 3.1+. The SDK has already
+handled the fork by the time `on_worker_boot` runs, and since 1.4.0 a
+`Quonfig.fork` call in a child the hook has already prepared simply returns
+the same client (so a leftover call from older docs is harmless):
 
 ```ruby
-# config/puma.rb (Ruby 3.0 only)
-before_fork do
-  Quonfig.instance.stop          # close the master's SSE before forking
+# config/puma.rb (Ruby 3.1+)
+on_worker_boot do
+  SemanticLogger.reopen
 end
+```
 
+If you're on Ruby 3.0 (no `Process._fork`), wire the worker boot hook
+manually:
+
+```ruby
+# config/puma.rb (Ruby 3.0 only)
 on_worker_boot do
-  Quonfig.fork                   # rebuild a fresh client per worker
+  Quonfig.fork          # rebuild a fresh client per worker
+  SemanticLogger.reopen # if you use SemanticLogger
 end
 ```
 
+Do **not** add a `before_fork { Quonfig.instance.stop }` — the master's
+client does not need to be torn down for the workers to be healthy, and
+stopping it means the master stops receiving config.
+
 ### Sidekiq
 
-On Ruby 3.1+ the automatic fork hook covers Sidekiq workers too — no
-`configure_server` wiring required.
+Sidekiq OSS does not fork: it runs jobs on threads inside one process, so
+`Quonfig.init` in your initializer is all you need on any Ruby version.
 
-On Ruby 3.0:
+Some jobs *do* fork — the `parallel` gem, an explicit `fork { ... }`, or
+Sidekiq Enterprise's swarm mode. On Ruby 3.1+ those are covered
+automatically, with nothing to call, and (since 1.4.0) the Sidekiq process
+itself keeps streaming config the whole time.
 
-```ruby
-# config/initializers/quonfig.rb
-Quonfig.init(Quonfig::Options.new(sdk_key: ENV.fetch('QUONFIG_BACKEND_SDK_KEY')))
+Ruby 3.0 is end-of-life and has no `Process._fork` hook. The `parallel` gem
+has no per-worker boot hook to wire a rebuild into either — `Parallel.each`
+just runs your block in each child, once per row — so calling `Quonfig.fork`
+at the top of the block builds a **new client per row**, each with its own
+SSE stream and telemetry reporter. Upgrade to 3.1+ if you can. If you must
+stay on 3.0, rebuild once per child process by memoizing on the pid:
 
-# 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 }
+```ruby
+# Ruby 3.0 only — one rebuild per child process, not one per row.
+Parallel.each(batch, in_processes: 4) do |row|
+  Quonfig.fork if $quonfig_pid != Process.pid
+  $quonfig_pid = Process.pid
+  # ...
 end
 ```
 
-For Sidekiq web/CLI processes that don't fork (default `concurrency: 1`),
-`Quonfig.init` in the initializer is sufficient on any Ruby version.
-
 ### Spring / Bootsnap preloaders
 
-Spring forks the preloader for each command. If your initializer creates a
-Quonfig client at boot, the SSE thread will be inherited dead in every child.
-Two options:
+Spring forks the preloader for each command. On Ruby 3.1+ the automatic hook
+already rebuilds the client in each spawned command, and the preloader itself
+keeps streaming. On Ruby 3.0, either:
 
 1. **Recommended:** initialize lazily — wrap `Quonfig.init` so it only runs
    the first time `Quonfig.instance` is called from a non-preloader process.
 2. **Or:** call `Quonfig.fork` from a `Spring.after_fork` hook.
 
 ```ruby
-# config/spring.rb
+# config/spring.rb (Ruby 3.0 only)
 Spring.after_fork do
   Quonfig.fork if defined?(Quonfig) && Quonfig.instance_variable_get(:@singleton)
 end
@@ -528,8 +604,10 @@ envelope is intentional: a reader concurrent with envelope application may
 observe the new value for some keys and the old value for others, then
 converge once the envelope finishes applying.
 
-`Quonfig.fork` is the only safe way to "carry" a client across `Process.fork`
-— do not reuse the parent's client in a child process.
+Forking is handled for you on Ruby 3.1+: the child rebuilds automatically and
+the parent is left running (see [Rails integration](#rails-integration)). On
+Ruby 3.0, `Quonfig.fork` is the way to "carry" a client into a child — do not
+reuse the parent's client object in a child process without it.
 
 ## Diagnostic health signals
 

data/lib/quonfig/client.rb

@@ -21,14 +21,16 @@ module Quonfig
     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.)
+    # Client is tracked here so the hook can fan out 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; after_fork_in_child early-returns 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.)
+    #
+    # The registry is read in the CHILD only (qfg-lv4n.1) — the hook does
+    # nothing on the parent side, so no lock is taken across the syscall.
     @instances = ObjectSpace::WeakMap.new
     @instances_mutex = Mutex.new
 
@@ -43,8 +45,7 @@ module Quonfig
       end
     end
 
-    attr_reader :options, :resolver, :store, :evaluator, :instance_hash,
-                :config_loader, :telemetry_reporter
+    attr_reader :options, :instance_hash, :telemetry_reporter
 
     def initialize(options = nil, store: nil, **option_kwargs)
       @options =
@@ -82,6 +83,25 @@ module Quonfig
       @sse_ever_connected = false
       @fallback_engage_timer = nil
       @sse_terminal_failure = false
+      # The process that owns this client's threads, sockets, and store.
+      # Re-stamped when a child takes ownership in #rebuild_in_child!. A pid
+      # mismatch is PROOF that we are looking at a fork(2) child, which is
+      # what makes #owned_by_this_process? exact. See that method for why
+      # thread liveness could not answer the question.
+      @owner_pid = Process.pid
+      # Post-fork lazy re-initialization (qfg-lv4n.1). Set by
+      # +after_fork_in_child+; cleared by the first use of the client in the
+      # child. See #ensure_initialized_after_fork.
+      @fork_rebuild_pending = false
+      @fork_rebuild_mutex = Mutex.new
+      # The thread currently running the rebuild, so a re-entrant read (a
+      # SemanticLoggerFilter or stdlib formatter that calls +get+ from inside
+      # the rebuild's own logging) does not deadlock on the non-reentrant
+      # Mutex above.
+      @fork_rebuild_owner = nil
+      # Sticky init error under +on_init_failure: :raise+ (see
+      # #raise_sticky_fork_init_error).
+      @fork_rebuild_error = nil
 
       # If the caller injected a store, we're in test/bootstrap mode; skip I/O.
       return if store
@@ -103,6 +123,7 @@ module Quonfig
     # ---- Lookup --------------------------------------------------------
 
     def get(key, default = NO_DEFAULT_PROVIDED, jit_context = NO_DEFAULT_PROVIDED)
+      ensure_initialized_after_fork
       ctx = build_context(jit_context)
       record_context_for_telemetry(ctx)
       result =
@@ -186,10 +207,12 @@ module Quonfig
     end
 
     def defined?(key)
+      ensure_initialized_after_fork
       !@store.get(key).nil?
     end
 
     def keys
+      ensure_initialized_after_fork
       @store.keys
     end
 
@@ -312,51 +335,117 @@ module Quonfig
     end
 
     def stop
+      # Order matters (qfg-lv4n.1 D5). The flag goes up BEFORE we queue for
+      # the rebuild lock, so a post-fork rebuild already in flight sees it and
+      # skips starting an update channel and a telemetry reporter at all —
+      # otherwise it builds an SSE worker after we have finished tearing down
+      # and nothing is left holding a reference to close it.
       @stopped = true
-      tear_down_threaded_components!
+      # A child that never used the client must be able to stop it without
+      # paying for a re-initialization it never asked for.
+      @fork_rebuild_pending = false
+      @fork_rebuild_error = nil
+
+      # ...and the teardown itself is serialized against the rebuild, so it
+      # can never interleave with component construction. Re-entrancy: if the
+      # rebuild is what called `stop` (a customer on_update/logger hook), this
+      # thread already holds the lock.
+      if @fork_rebuild_owner == Thread.current
+        tear_down_threaded_components!
+      else
+        @fork_rebuild_mutex.synchronize { tear_down_threaded_components! }
+      end
     end
 
-    # 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.
+    # @deprecated Since 1.4.0 the +Process._fork+ hook NO LONGER CALLS THIS.
+    #   A fork must not disturb the process that forked: the parent keeps its
+    #   SSE stream, its poller, and its telemetry reporter, and keeps serving
+    #   live config (qfg-lv4n.1). This method is retained for semver and for
+    #   the Ruby 3.0 manual-wiring path, where a customer who genuinely wants
+    #   the parent torn down before a fork can still call it. Prefer +stop+
+    #   if you want the client dead.
     #
-    # 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.
+    # Closes the SSE worker, polling supervisor, telemetry reporter, datadir
+    # watcher, and any fallback-engage timer. Idempotent. Does NOT set
+    # +@stopped+, so +after_fork_in_child+ can still rebuild.
     def before_fork_in_parent
       return if @stopped
 
       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).
+    # Post-fork hook, run IN THE CHILD ONLY (see Quonfig::ForkSafety).
+    #
+    # Ruby threads do not survive fork(2), so everything threaded the child
+    # inherited is a dead reference. The child drops those references and
+    # rebuilds from scratch — matching Reforge's +Reforge.fork+, which simply
+    # constructs a brand-new client and lets the inherited one be collected.
+    #
+    # Two things we deliberately do NOT do to the inherited objects:
+    #
+    # * **Never close the inherited SSE socket.** fork(2) duplicates the fd,
+    #   so the child's copy points at the connection the PARENT is still
+    #   streaming on. Closing a TLS socket writes a +close_notify+ alert onto
+    #   that shared connection and kills the parent's stream. Dropping the
+    #   reference leaves the parent's fd untouched.
+    # * **Never join an inherited thread.** The thread does not exist in the
+    #   child, so a +join+/+stop+ that waits on it blocks forever (see
+    #   LaunchDarkly ruby-server-sdk PR #430: "close blocks forever, because
+    #   EventProcessor#stop waits for a dispatcher thread that does not
+    #   exist").
+    #
+    # No-op if the client was already stopped — the customer asked for it to
+    # be dead, and a fork must not resurrect it.
+    #
+    # Also a no-op in the process that OWNS the client, i.e. the PARENT —
+    # decided by a pid stamp, not by whether anything looks alive. Releases
+    # 1.0-1.3 documented calling this in the parent as the workaround for the
+    # parent going dark after a fork; on 1.4.0+ such a call would orphan the
+    # parent's live components and zero its store, so it is ignored (one
+    # debug line). See #owned_by_this_process?.
+    #
+    # The hook does NO I/O: no fetch, no socket, no thread. It throws away
+    # everything the child inherited — including the parent's config snapshot
+    # — and arms a flag. The child re-initializes on its FIRST use of the
+    # client (see #ensure_initialized_after_fork), exactly like a newly
+    # constructed client would. A child that never uses the client, which is
+    # most of them in a `Parallel.map` batch, costs nothing at all.
     def after_fork_in_child
       return if @stopped
+      return if owned_by_this_process?
 
-      if @options.datadir
-        start_datadir_watcher if @options.data_dir_auto_reload
-        return
-      end
+      # The inherited Mutexes may be held by threads that no longer exist.
+      # Only this thread exists in a fresh child, so swapping them is safe.
+      @state_mutex = Mutex.new
+      @fork_rebuild_mutex = Mutex.new
+      @fork_rebuild_owner = nil
+      @fork_rebuild_error = nil
+      drop_inherited_threaded_components!
 
-      return if @config_loader.nil? # never finished network init (e.g. invalid key)
+      # SSE state machine carries flags that describe the PARENT's session
+      # (it had connected, it had errored, ...). None of them apply here.
+      @sse_state = :idle
+      @sse_ever_connected = false
+      @sse_terminal_failure = false
+      @sse_error_callback = nil
 
-      # 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
+      # A client that never finished network init has nothing to rebuild.
+      return if @config_loader.nil? && !@options.datadir
 
-      sse_started = @options.enable_sse && start_sse
-      start_polling if @options.fallback_poll_enabled && !sse_started
+      # A brand-new, EMPTY store. The child must not evaluate from whatever
+      # snapshot the parent happened to hold at the instant of the fork: it
+      # fetches (or loads) its own on first use.
+      reset_store_in_child!
 
-      restart_telemetry_in_child
+      # Fresh aggregators. The parent flushes its own copy; a child that
+      # flushed inherited data would double-report it. The reporter is BUILT
+      # here (so the child's config loader points at the child's failover
+      # aggregator) but NOT started — starting it is I/O, and that waits for
+      # first use.
+      rebuild_aggregators_in_child!
+
+      @forked_in_pid = Process.pid
+      @fork_rebuild_pending = true
     end
 
     # quonfig_sdk_worker_restart_total counter (Tier 1 supervisor contract).
@@ -409,7 +498,17 @@ module Quonfig
     def connection_state
       @state_mutex.synchronize do
         next :disconnected if @stopped
+        # Forked, not yet used: nothing has been fetched and nothing is
+        # running. Saying so is the honest answer, and a diagnostic must not
+        # be what triggers a blocking fetch.
+        next :initializing if @fork_rebuild_pending
         next :falling_back if @poll_supervisor&.alive?
+        # Liveness beats the stored flag (qfg-lv4n.1). A client whose SSE
+        # session was torn down keeps a stale @sse_state; answering
+        # :connected off that flag is how a dark client reported healthy for
+        # 13 days. If this client is supposed to have a live SSE worker and
+        # does not, it is disconnected — whatever the flag says.
+        next :disconnected if sse_channel_expected? && !sse_worker_alive?
         next :connected if @sse_state == :connected
         next :disconnected if @sse_state == :error
 
@@ -461,7 +560,65 @@ module Quonfig
       sse.failed_over_to_secondary?
     end
 
+    # ---- Component readers ---------------------------------------------
+    #
+    # Public since 1.0 and kept public for semver. Each one routes through
+    # the post-fork chokepoint: in a forked child that has not been used yet
+    # the raw components read an EMPTY store (+store.get+ answered nil,
+    # +resolver.get+ raised MissingDefaultError), so handing them back
+    # without re-initializing is handing back a component that lies
+    # (qfg-lv4n.1 D6).
+
+    # @return [Quonfig::ConfigStore] the store backing this client.
+    # @note In a forked child, reading this triggers the lazy post-fork
+    #   re-initialization (see #after_fork_in_child) — it can block on the
+    #   child's own config fetch.
+    def store
+      ensure_initialized_after_fork
+      @store
+    end
+
+    # @return [Quonfig::Resolver]
+    # @note (see #store)
+    def resolver
+      ensure_initialized_after_fork
+      @resolver
+    end
+
+    # @return [Quonfig::Evaluator]
+    # @note (see #store)
+    def evaluator
+      ensure_initialized_after_fork
+      @evaluator
+    end
+
+    # @return [Quonfig::ConfigLoader, nil] nil in datadir mode.
+    # @note (see #store)
+    def config_loader
+      ensure_initialized_after_fork
+      @config_loader
+    end
+
+    # A client to use in a forked child.
+    #
+    # On Ruby 3.1+ the +Process._fork+ hook has already prepared THIS client
+    # in the child by the time any user code runs there (inherited threads
+    # and store dropped, re-initialization armed for first use). A call here
+    # in that child — the +on_worker_boot { Quonfig.fork }+ line the 1.0–1.3
+    # README taught — therefore returns +self+: the hook already did what the
+    # caller is asking for. Building a second client instead would discard
+    # the prepared one and pay an eager second fetch, or, after first use,
+    # leave the worker holding two live SSE streams and two reporters with
+    # the first pair orphaned where +stop+ can never reach it (qfg-4t5o).
+    #
+    # Everywhere else — the owning process, Ruby 3.0 where there is no hook,
+    # a client that was +stop+ped before the fork — this builds a fresh
+    # client, which is the Ruby 3.0 manual-wiring path. The old client is
+    # never stopped: on 3.0 it is the inherited one, and stopping it would
+    # close the inherited socket and tear down the PARENT's stream.
     def fork
+      return self if @forked_in_pid == Process.pid
+
       self.class.new(@options.for_fork)
     end
 
@@ -471,10 +628,73 @@ 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).
+    # True when THIS process is the one that owns the client — i.e. we are
+    # the parent, not a fork(2) child.
+    #
+    # The answer is a pid comparison against the stamp taken when the client
+    # was constructed (and re-taken when a child rebuilds it). A pid mismatch
+    # is PROOF of a fork child; a match is proof that nobody forked.
+    #
+    # It deliberately does NOT ask whether any component looks alive, which
+    # is what 1.4.0 shipped and what got this wrong at both ends:
+    #
+    # * **False negative in a real child.** +on_update+ runs on the SSE worker
+    #   thread, so a customer who forks from that callback forks ON it — and
+    #   the inherited +@worker.alive?+ is therefore true in the child. The
+    #   child was classified as the parent, ignored the hook, served the
+    #   parent's snapshot forever and reported +:connected+ (qfg-lv4n.1 E1).
+    # * **False positive in a real parent.** A datadir client with
+    #   auto-reload off and no SDK key has no threads and no reporter at all,
+    #   so the guard let a parent-side call through and it wiped the live
+    #   store (qfg-lv4n.1 E4/D4).
+    #
+    # The parent case is what makes a stray +after_fork_in_child+ call a
+    # no-op. Releases 1.0-1.3 documented exactly that call as the workaround
+    # for the parent-keeps-evaluating topology, and that code is still out
+    # there: on 1.4.0+ it would orphan the live SSE worker and its stream,
+    # zero the store, and stop the owner's telemetry reporter.
+    def owned_by_this_process?
+      return false unless @owner_pid == Process.pid
+
+      LOG.debug '[quonfig] after_fork_in_child called in the process that OWNS the client ' \
+                "(pid=#{Process.pid}); ignoring. Since 1.4.0 a fork never touches the " \
+                'process that forked, and the child-side rebuild is automatic on Ruby 3.1+.'
+      true
+    end
+
+    # True when this client is a network-mode client that asked for SSE, i.e.
+    # one that is SUPPOSED to be holding a live stream. Datadir clients and
+    # store-injected (test/bootstrap) clients never are, so their
+    # +connection_state+ keeps deriving from envelope installs alone.
+    def sse_channel_expected?
+      return false if @options.datadir
+      return false unless @options.enable_sse
+
+      !@config_loader.nil?
+    end
+
+    # Is there an SSE worker thread actually running right now? Note this
+    # stays true across a reconnect: the worker owns the retry loop, so a
+    # blip does not read as "no channel".
+    def sse_worker_alive?
+      sse = @sse_client
+      return false if sse.nil?
+      return true unless sse.respond_to?(:alive?)
+
+      sse.alive?
+    end
+
+    # Close every threaded component and drop its reference. Used by +stop+
+    # (where @stopped is also flipped) and by the deprecated manual
+    # +before_fork_in_parent+ (where @stopped is left alone). NOT reachable
+    # from the fork hook any more — a fork never touches the process that
+    # forked (qfg-lv4n.1).
     def tear_down_threaded_components!
+      # The SSE state machine describes a session that no longer exists.
+      # Leaving @sse_state == :connected behind is how `connection_state`
+      # came to answer :connected for a client with nothing alive.
+      @state_mutex.synchronize { @sse_state = :idle }
+
       begin
         @sse_client&.close
       rescue StandardError => e
@@ -506,11 +726,233 @@ module Quonfig
       @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
+    # Drop every inherited threaded component WITHOUT closing, stopping, or
+    # joining it. See the comment on +after_fork_in_child+ for why touching
+    # these objects in the child is actively harmful (shared socket fds,
+    # threads that do not exist). Reforge, LaunchDarkly, dd-trace-rb,
+    # redis-client and connection_pool all do exactly this.
+    def drop_inherited_threaded_components!
+      inherited_reporter = @telemetry_reporter
+
+      @sse_client = nil
+      @poll_supervisor = nil
       @telemetry_reporter = nil
-      initialize_telemetry
+      @datadir_watcher = nil
+      @fallback_engage_timer = nil
+
+      # Dropping our reference is not enough for the reporter: its
+      # `Kernel.at_exit { final_drain_on_exit }` closure is process-wide, it
+      # was copied by fork(2), and it still holds a full copy of the PARENT's
+      # un-flushed telemetry window. The reporter's own owner-pid guard is
+      # what makes that closure inert (see TelemetryReporter#start); this
+      # additionally makes the copied window unreachable. Neither stops,
+      # closes, nor joins anything.
+      begin
+        inherited_reporter&.discard_inherited!
+      rescue StandardError => e
+        LOG.debug "Error discarding inherited telemetry reporter: #{e.message}"
+      end
+    end
+
+    # Lazy post-fork re-initialization. Called from every read entry point
+    # (+get+, +evaluate_details+, +defined?+, +keys+) — the flag read is a
+    # plain boolean, so the steady-state cost is one comparison per lookup.
+    #
+    # The first caller in the child does what +Client.new+ does: its own
+    # config fetch under the configured init timeout and +on_init_failure+
+    # policy, then its own SSE stream (or fallback poller) and its own
+    # telemetry reporter. It BLOCKS, so that first lookup already reflects
+    # the child's own current config.
+    #
+    # +connection_state+ deliberately does NOT trigger this: a diagnostic
+    # must never open a socket. It reports +:initializing+ while a rebuild is
+    # pending, which is exactly what the client is.
+    def ensure_initialized_after_fork
+      # Hot path: two ivar reads and no lock. Both are falsy for every client
+      # that has never been through a fork.
+      return unless @fork_rebuild_pending || @fork_rebuild_error
+      # Re-entrancy guard: a customer logger (SemanticLoggerFilter, stdlib
+      # formatter) that evaluates a config from inside the rebuild would
+      # otherwise deadlock on the non-reentrant Mutex. Such a call sees the
+      # half-built client, which is the same thing Client.new gives a logger
+      # that fires during construction.
+      return if @fork_rebuild_owner == Thread.current
+
+      run_pending_child_rebuild if @fork_rebuild_pending
+      raise_sticky_fork_init_error if @fork_rebuild_error
+    end
+
+    # Run the rebuild under the lock, or block until whoever is running it is
+    # done. The flag stays TRUE for the whole rebuild, which is what makes
+    # every other first-use caller take the mutex and WAIT rather than sail
+    # past on the unlocked fast path and evaluate against the empty store.
+    def run_pending_child_rebuild
+      @fork_rebuild_mutex.synchronize do
+        # Lost the race: the winner already rebuilt (or `stop` disarmed us).
+        return unless @fork_rebuild_pending
+        return if @stopped
+
+        @fork_rebuild_owner = Thread.current
+        begin
+          rebuild_in_child!
+        rescue StandardError => e
+          # Handled: the child gets whatever healing path its mode allows, so
+          # the next lookup must not re-run the blocking fetch. (The datadir
+          # recovery path may deliberately re-arm — see
+          # #recover_datadir_child_after_failed_rebuild.)
+          @fork_rebuild_pending = false
+          handle_child_rebuild_failure(e)
+        ensure
+          @fork_rebuild_owner = nil
+          # #rebuild_in_child! disarms the flag itself the moment the child
+          # has a live path to config. Anything that escapes before that —
+          # including a non-StandardError such as rack-timeout's
+          # RequestTimeoutException, Ruby 3.3's Timeout::ExitException, or a
+          # Thread#kill, none of which the rescue above can see — leaves the
+          # flag armed so the NEXT call retries instead of leaving the child
+          # dark forever (qfg-lv4n.1 D2).
+          @fork_rebuild_pending = false if @stopped
+        end
+      end
+    end
+
+    # Under +on_init_failure: :raise+ a failed rebuild raises out of the call
+    # that triggered it, exactly as +Client.new+ would — and keeps raising on
+    # subsequent calls (without re-fetching) until the update channel heals
+    # the store. Under +:return+ nothing is stored here and this never fires.
+    def raise_sticky_fork_init_error
+      err = @fork_rebuild_error
+      return if err.nil?
+
+      if ready?
+        # The SSE stream (or the poller) installed an envelope: the client is
+        # serving real config again, so the init failure is history.
+        @fork_rebuild_error = nil
+        return
+      end
+
+      raise err
+    end
+
+    # A rebuild that raised. Log it, give the child whatever healing path its
+    # mode has, and honor +on_init_failure+.
+    def handle_child_rebuild_failure(err)
+      LOG.error "[quonfig] post-fork re-initialization failed: #{err.class}: #{err.message}"
+
+      if @options.datadir
+        recover_datadir_child_after_failed_rebuild
+      else
+        begin
+          start_update_channel if @sse_client.nil? && @poll_supervisor.nil?
+        rescue StandardError => e
+          LOG.error "[quonfig] post-fork update channel failed to start: #{e.class}: #{e.message}"
+        end
+      end
+
+      return unless @options.on_init_failure == Quonfig::Options::ON_INITIALIZATION_FAILURE::RAISE
+
+      # Parity with a fresh Client.new, which raises under :raise. Stored so
+      # later calls keep raising rather than re-running the fetch on every
+      # lookup.
+      @fork_rebuild_error = err
+      raise err
+    end
+
+    # A datadir client is configured OFFLINE: it has no config loader, so
+    # opening an SSE stream here dials the network on a customer who asked
+    # for none and then blows up on every envelope that arrives
+    # ("undefined method `apply_envelope' for nil"). The healing path for a
+    # datadir child is the filesystem: start the watcher if auto-reload is on
+    # so a repaired workspace is picked up, and otherwise re-arm the rebuild
+    # so the next use retries the load (qfg-lv4n.1 D3).
+    def recover_datadir_child_after_failed_rebuild
+      begin
+        start_datadir_watcher if @options.data_dir_auto_reload && @datadir_watcher.nil?
+      rescue StandardError => e
+        LOG.error "[quonfig] post-fork datadir watcher failed to start: #{e.class}: #{e.message}"
+      end
+
+      return unless @datadir_watcher.nil?
+
+      @fork_rebuild_pending = true
+    end
+
+    # The child's own re-initialization, run on first use. Mirrors what
+    # +Client.new+ does for this client's mode, and logs one info line so a
+    # customer grepping their logs can see the SDK noticed the fork.
+    def rebuild_in_child!
+      # This process is taking ownership of the client. Re-stamping here is
+      # what keeps #owned_by_this_process? exact for everything that follows:
+      # a manual +after_fork_in_child+ in THIS child is now correctly a
+      # no-op, and a grandchild forked from here is still detected by pid.
+      @owner_pid = Process.pid
+      components = []
+
+      if @options.datadir
+        load_datadir_into_store
+        components << 'datadir'
+        start_datadir_watcher if @options.data_dir_auto_reload
+        components << 'datadir-watcher' if @datadir_watcher
+      else
+        initialize_network_mode
+        components << 'config' if ready?
+        components << 'sse' if @sse_client
+        components << 'polling' if @poll_supervisor
+      end
+
+      # The child now has a live path to config (a stream/poller, or a loaded
+      # datadir). Disarm HERE, not in the caller: everything above is
+      # retryable and must stay armed if it is interrupted, and everything
+      # below must never re-run the fetch or dial a second stream.
+      @fork_rebuild_pending = false
+
+      unless @stopped
+        @telemetry_reporter&.start
+        components << 'telemetry' if @telemetry_reporter
+      end
+
+      log_child_rebuild(components)
+    end
+
+    # A brand-new store (plus the evaluator, resolver, and config loader that
+    # read it) so the child starts from nothing and installs its own envelope.
+    # Two things this buys beyond "no stale config": the child's first
+    # envelope is ACCEPTED rather than dropped by the reject-older guard as
+    # same-generation, and a fork that lands mid-install can no longer hand
+    # the child a half-written store.
+    def reset_store_in_child!
+      @store = Quonfig::ConfigStore.new
+      @evaluator = Quonfig::Evaluator.new(@store, env_id: @options.environment)
+      @resolver = Quonfig::Resolver.new(@store, @evaluator)
+      @last_successful_refresh = nil
+      return if @options.datadir
+
+      @config_loader = Quonfig::ConfigLoader.new(@store, @options, failover_aggregator: @failover_aggregator)
+    end
+
+    # Replace every aggregator with a fresh, empty one so the child never
+    # re-reports data the parent collected (and is still going to flush from
+    # its own copy). Mirrors what a brand-new Client.new would allocate.
+    def rebuild_aggregators_in_child!
+      @failover_aggregator = Quonfig::Telemetry::FailoverAggregator.new
+      # The ConfigLoader records hedge/guard/resolved-from at its failover
+      # call sites, so it has to point at the child's aggregator too — the
+      # inherited one is now the parent's private object.
+      @config_loader.failover_aggregator = @failover_aggregator if @config_loader.respond_to?(:failover_aggregator=)
+
+      # initialize_telemetry allocates fresh context/example/summaries
+      # aggregators and a fresh reporter. It is NOT started here: starting the
+      # reporter is I/O and a thread, and both wait for the child's first use.
+      @telemetry_reporter = nil
+      initialize_telemetry(start: false)
+    end
+
+    # One line, at info, so a customer can see in their logs that the SDK
+    # noticed the fork and rebuilt. Deliberately not a warning: forking is
+    # normal and expected.
+    def log_child_rebuild(components)
+      list = components.empty? ? 'none' : components.join(',')
+      LOG.info "[quonfig] re-initialized after fork pid=#{Process.pid} components=#{list}"
     end
 
     # Stamp +last_successful_refresh+ at install time. Called by every code
@@ -668,7 +1110,7 @@ module Quonfig
     # Construct and start the telemetry reporter if the options permit it.
     # The reporter runs on a background thread and periodically POSTs
     # context-shape and example-context batches to +telemetry_destination+.
-    def initialize_telemetry
+    def initialize_telemetry(start: true)
       shape_aggregator = nil
       example_aggregator = nil
       summaries_aggregator = nil
@@ -704,6 +1146,7 @@ module Quonfig
       )
 
       return unless @telemetry_reporter.enabled?
+      return unless start
 
       @telemetry_reporter.start
     rescue StandardError => e
@@ -826,15 +1269,32 @@ module Quonfig
       warn_if_hedge_abort_exceeds_init_timeout
       warn_if_explicit_api_urls_disables_failover
 
-      @config_loader = Quonfig::ConfigLoader.new(@store, @options, failover_aggregator: @failover_aggregator)
+      # ||=: after a fork the child already built its loader over its fresh
+      # store (see #reset_store_in_child!).
+      @config_loader ||= Quonfig::ConfigLoader.new(@store, @options, failover_aggregator: @failover_aggregator)
 
       perform_initial_fetch
+      start_update_channel
+    end
 
-      sse_started = @options.enable_sse && start_sse
+    # SSE if enabled and it comes up; otherwise the HTTP polling fallback.
+    # Polling is a fallback: if SSE is off or failed to start, poll. This
+    # avoids double-work when SSE is healthy but still refreshes the store in
+    # environments that block SSE (corporate proxies, Lambda, etc.).
+    def start_update_channel
+      # A `stop` that raced the post-fork rebuild must win: never dial a
+      # stream for a client the customer has already killed (qfg-lv4n.1).
+      return if @stopped
+      # Idempotent. `rebuild_in_child!` disarms @fork_rebuild_pending only
+      # AFTER initialize_network_mode has already started the channel, so a
+      # non-StandardError landing in that window (rack-timeout,
+      # Timeout::ExitException, Thread#kill) leaves the flag armed WITH a
+      # live stream. The retry re-runs initialize_network_mode; without this
+      # guard it dialled a SECOND stream and overwrote @sse_client, orphaning
+      # the first worker where `stop` could never reach it (qfg-lv4n.1 E2).
+      return if sse_worker_alive? || @poll_supervisor&.alive?
 
-      # Polling is a fallback: if SSE is off or failed to start, poll. This
-      # avoids double-work when SSE is healthy but still refreshes the store
-      # in environments that block SSE (corporate proxies, Lambda, etc.).
+      sse_started = @options.enable_sse && start_sse
       start_polling if @options.enable_polling && !sse_started
     end
 
@@ -959,6 +1419,7 @@ module Quonfig
     # Returns true if SSE started successfully, false otherwise. A false here
     # signals the caller to fall back to polling.
     def start_sse
+      return false if @stopped
       return false if @options.sse_api_urls.nil? || @options.sse_api_urls.empty?
 
       @sse_client = Quonfig::SSEConfigClient.new(
@@ -1143,6 +1604,7 @@ module Quonfig
     # caller's context, after coercing/checking +expected_type+. Never
     # raises; all exceptions become ERROR details.
     def evaluate_details(key, expected_type, context)
+      ensure_initialized_after_fork
       jit = context == NO_DEFAULT_PROVIDED ? nil : context
       ctx = build_context(jit)
       record_context_for_telemetry(ctx)
@@ -1282,32 +1744,52 @@ module Quonfig
     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.
+  # qfg-ryov / qfg-lv4n.1: hook into Process._fork so customers using Puma's
+  # clustered mode (or any preload/fork-worker server, or a gem that forks
+  # inside a job) 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.
+  # **The hook is child-only.** Nothing happens in the parent — not before
+  # the syscall, not after it. A fork is somebody else's business; the
+  # process that forked keeps its SSE stream, its poller, its telemetry
+  # reporter, and its live config. This is Reforge's model (+Reforge.fork+
+  # builds a new client in the child and never touches the old one) and
+  # matches dd-trace-rb, redis-client and connection_pool, which all branch
+  # on the child stage of +_fork+ only.
+  #
+  # It replaces the qfg-ryov shape, which tore the parent down before the
+  # syscall on the theory that the child must not inherit a live socket fd.
+  # That was wrong twice over: the child never touches the inherited fd (it
+  # drops the reference — see Client#after_fork_in_child), and a Sidekiq
+  # parent that forks a worker and keeps evaluating went dark for 13 days in
+  # production.
   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?
+      if pid.zero?
+        # Per-instance, not per-fan-out: a process can hold more than one
+        # Client (a second workspace, a test harness, a gem that builds its
+        # own). One of them failing to rebuild — thread exhaustion, a
+        # customer logger that raises — must not cost every client behind it
+        # in the registry its rebuild and leave the child silently dark.
+        Quonfig::Client.each_instance do |client|
+          client.after_fork_in_child
+        rescue StandardError => e
+          Quonfig::Client::LOG.error 'Quonfig fork rebuild failed for one client ' \
+                                     "(continuing with the rest): #{e.class}: #{e.message}"
+        end
+      end
       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.
+      # the child holds dropped references and no live threads — 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
 

data/lib/quonfig/config_loader.rb

@@ -31,6 +31,12 @@ module Quonfig
     #                     SSE does not change it).
     attr_reader :held_generation, :install_count
 
+    # Repoint the failover-telemetry sink. The one caller is
+    # Client#after_fork_in_child: a forked child gets fresh aggregators (the
+    # parent still owns and flushes its own), and the loader has to record
+    # into the child's copy rather than the inherited one (qfg-lv4n.1).
+    attr_writer :failover_aggregator
+
     # +store+: the Quonfig::ConfigStore to populate on successful fetch.
     # +options+: a Quonfig::Options instance (supplies sdk_key + config_api_urls).
     # +logger+: optional logger override (defaults to module LOG).

data/lib/quonfig/sse_config_client.rb

@@ -129,6 +129,15 @@ module Quonfig
       @worker = Thread.new { run_loop(&on_envelope) }
     end
 
+    # True while the worker thread that owns the stream (and its reconnect
+    # loop) is running. Stays true across a reconnect — the worker owns the
+    # retry, so a blip is not "no channel". Used by Client#connection_state
+    # so that diagnostic derives from liveness rather than a stored flag
+    # (qfg-lv4n.1).
+    def alive?
+      @worker&.alive? || false
+    end
+
     # Shut down. Interrupts the in-flight stream by closing the underlying
     # socket from this thread — the worker thread observes the resulting
     # IOError, sees @stopped == true, and exits cleanly.

data/lib/quonfig/telemetry/telemetry_reporter.rb

@@ -51,6 +51,9 @@ module Quonfig
         @stopped = Concurrent::AtomicBoolean.new(false)
         @thread = nil
         @at_exit_registered = false
+        # Set on #start. Everything that can EMIT is gated on it so a forked
+        # child never speaks for the process that created this reporter.
+        @owner_pid = nil
       end
 
       def enabled?
@@ -80,6 +83,11 @@ module Quonfig
         return if @thread&.alive?
         return unless enabled?
 
+        # Claim ownership for THIS process. fork(2) copies the reporter, its
+        # aggregators, and the process-wide at_exit closure registered below;
+        # the pid recorded here is what lets the copy know it is not the
+        # owner and must stay silent (qfg-lv4n.1, dd-trace-rb's pattern).
+        @owner_pid = Process.pid
         @stopped.make_false
         register_at_exit_handler
         @thread = Thread.new do
@@ -106,6 +114,8 @@ module Quonfig
       end
 
       def stop
+        return if foreign_process?('stop')
+
         @stopped.make_true
         thread = @thread
         @thread = nil
@@ -121,7 +131,13 @@ module Quonfig
 
       # Drain all aggregators and POST the batch. Public so tests can
       # trigger a sync without waiting for the background loop.
+      #
+      # Silent in any process other than the one that started the reporter:
+      # after a fork the child holds a full copy of the PARENT's un-flushed
+      # window, and the parent is still going to flush it itself.
       def sync
+        return if foreign_process?('sync')
+
         events = []
         if (summaries_event = @evaluation_summaries_aggregator&.drain_event)
           events << summaries_event
@@ -151,8 +167,41 @@ module Quonfig
         @at_exit_registered
       end
 
+      # Pid of the process that started this reporter, or nil if it was never
+      # started. Visible for tests / diagnostics.
+      attr_reader :owner_pid
+
+      # Called on the INHERITED reporter in a forked child, from
+      # +Quonfig::Client#after_fork_in_child+, once the child has dropped its
+      # reference to it. Makes the copied window unreachable so nothing can
+      # ever emit it — belt to the +@owner_pid+ braces.
+      #
+      # Deliberately does NOT stop, close, or join anything: the thread does
+      # not exist in the child, and the HTTP connection's fd is shared with
+      # the parent.
+      def discard_inherited!
+        @stopped.make_true
+        @thread = nil
+        @context_shape_aggregator = nil
+        @example_contexts_aggregator = nil
+        @evaluation_summaries_aggregator = nil
+        @failover_aggregator = nil
+      end
+
       private
 
+      # True when this reporter belongs to a different process — i.e. we are
+      # a fork(2) copy. Never true before #start (nothing has been claimed,
+      # and nothing was registered at_exit either).
+      def foreign_process?(operation)
+        return false if @owner_pid.nil?
+        return false if @owner_pid == Process.pid
+
+        LOG.debug "[quonfig] Telemetry #{operation} skipped in forked child " \
+                  "pid=#{Process.pid} owner_pid=#{@owner_pid}"
+        true
+      end
+
       # Rails / Passenger / Puma workers often terminate via SIGTERM without
       # a chance to call Client#stop. Register a Kernel.at_exit hook on
       # first start so the in-flight batch still gets flushed.
@@ -174,6 +223,8 @@ module Quonfig
       # no-op. Bounded so a stuck reporter thread or dead telemetry
       # endpoint can't hang process exit.
       def final_drain_on_exit
+        return if foreign_process?('at_exit drain')
+
         @stopped.make_true
         thread = @thread
         @thread = nil

data/lib/quonfig/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quonfig
-  VERSION = '1.3.0'
+  VERSION = '1.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport