shipeasy-sdk 2.4.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 991e86824a2b5fb735a7d7f53dbff73c635f1a4adb5a3056e3b5c359a164dcbc
-  data.tar.gz: 897872d04e78e03dd76f26b5e82108a5a18ef7eea749cf9657ced843e63843c4
+  metadata.gz: 3a34364fd54857fe0b04997063d9d2bbb6296e281a3db8b7389efd84c5f1b4a1
+  data.tar.gz: bb1c68285633d2f1a5709286197b9a0aacaf7c78d950908e414f3fde64f44144
 SHA512:
-  metadata.gz: 540e78bcb95b819ad2a74c8d69387f5ed252b9b6fc9c12ca89f0aa9b1d6ff1653197394721f35931808abb89fa0a4bc002ce7f1c152857e5e80bfd6759bf2c8e
-  data.tar.gz: 36a1275319ef6958380451dd186e0dcd90cbdb04110b0cdf96e59a5e013d8a7a730456672325f9445eae0c4e2ac5f9ace72c936f9d039d9575e0fbd4c5933889
+  metadata.gz: f4f9a1149dabefce47743afb04bec2e3f3e6dceac88c9e1a48a2cdb187b87bce0c5c9853cc68afe3f64f7a521fe8dcb4d5017c679ea362f19f8b598d71b3dbcb
+  data.tar.gz: b82a76824d4d0a90cc481453c5036a53cdb1adb30e74630ac843c6d6582fa294391e440b0d29b044eebf25071eb264bbab3a74491fac3939a815064ca1fd0f92

data/README.md

@@ -59,8 +59,8 @@ flags = Shipeasy::Client.new(current_user)
 
 flags.get_flag("new_checkout")                       # NO user arg — bound at construction
 flags.get_config("button_color")
-result = flags.get_experiment("checkout_cta", { label: "Buy" })
-flags.log_exposure("checkout_cta")                   # at the decision point
+assignment = flags.universe("checkout").assign       # <=1 experiment; auto-logs exposure
+assignment.get("label", "Buy")                       # variant ?? universe default ?? fallback
 flags.track("purchase", { revenue: 49 })             # on conversion
 flags.get_killswitch("payments")
 ```
@@ -78,7 +78,7 @@ Constructing `Shipeasy::Client.new(user)` before `Shipeasy.configure` raises
 | [Feature flags](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/flags.md) | `get_flag`, `get_flag_detail`, defaults. |
 | [Dynamic configs](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/configs.md) | `get_config`, typed decode, defaults. |
 | [Kill switches](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/killswitches.md) | `get_killswitch`, named switches. |
-| [Experiments](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/experiments.md) | `get_experiment`, `log_exposure`, `track`. |
+| [Experiments](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/experiments.md) | `universe(name).assign`, `Assignment#get`, `track`. |
 | [Internationalization](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/i18n.md) | Rails view helpers + the SSR loader tag. |
 | [Error reporting](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/error-reporting.md) | `see()` structured error reporting. |
 | [Testing](https://github.com/shipeasy-ai/sdk-ruby/blob/main/docs/pages/testing.md) | `configure_for_testing` / `configure_for_offline`, overrides. |
@@ -109,12 +109,15 @@ client = Shipeasy::Client.new({ "user_id" => "u_123" })
 client.get_flag("new_checkout")              # => true
 client.get_config("billing_copy")            # => { "title" => "Welcome" }
 
-result = client.get_experiment("checkout_button", { "color" => "blue" })
-result.in_experiment                         # => true
-result.group                                 # => "treatment"
-result.params                                # => { "color" => "green" }
+# An experiment override surfaces through universe(name).assign once the loaded
+# blob maps that experiment to its universe (an offline snapshot does this; a
+# bare configure_for_testing has no blob). Read via the universe:
+assignment = client.universe("checkout").assign
+assignment.enrolled?                         # => true
+assignment.group                             # => "treatment"
+assignment.get("color")                      # => "green"
 
-# track / log_exposure are no-ops in test mode — safe to call, send nothing
+# track / assign exposures are no-ops in test mode — safe to call, send nothing
 client.track("purchase", { amount: 49 })
 ```
 

data/docs/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shipeasy-ruby
-description: Use Shipeasy (feature flags, configs, kill switches, A/B experiments, i18n) from Ruby. Covers Shipeasy.configure + Client.new(user), get_flag/get_config/get_experiment/get_killswitch, track, testing, OpenFeature.
+description: Use Shipeasy (feature flags, configs, kill switches, A/B experiments, i18n) from Ruby. Covers Shipeasy.configure + Client.new(user), get_flag/get_config/universe(name).assign/get_killswitch, track, testing, OpenFeature.
 ---
 
 # Shipeasy Ruby SDK
@@ -46,8 +46,10 @@ the default (one-shot fetch, no thread) is serverless-friendly.
 
 ## Evaluate (bound `Client.new(user)` — NO user arg)
 
-Bind the user once per request, then call without re-passing it — `track` and
-`log_exposure` are on the bound client too, so experiments are end-to-end here:
+Bind the user once per request, then call without re-passing it — experiments
+are read by **universe** (a mutual-exclusion pool: the unit lands in <=1
+experiment), and `track` is on the same bound client, so experiments are
+end-to-end here:
 
 ```ruby
 flags = Shipeasy::Client.new(current_user)   # runs the attributes transform once
@@ -55,10 +57,13 @@ flags = Shipeasy::Client.new(current_user)   # runs the attributes transform onc
 flags.get_flag("new_checkout")               # bool; default: only when unresolved
 flags.get_config("button_color", default: "blue")
 flags.get_killswitch("payments")             # true = killed; optional switch_key
-result = flags.get_experiment("checkout_cta", { label: "Buy now" })
-# result.in_experiment / result.group / result.params
 
-flags.log_exposure("checkout_cta")           # at the decision point
+# Ask the UNIVERSE, not the experiment. Returns an Assignment (never raises):
+#   .name / .group  → nil when not enrolled ·  .enrolled?  → group non-nil
+#   .get(field, fallback = nil) → variant override ?? universe default ?? fallback
+assignment = flags.universe("checkout").assign   # auto-logs one deduped exposure when enrolled
+render_cta(assignment.get("label", "Buy now"))
+
 flags.track("purchase", { revenue: 49 })     # conversion / metric event
 ```
 

data/lib/shipeasy/client.rb

@@ -4,7 +4,7 @@ module Shipeasy
   #
   #   flags = Shipeasy::Client.new(current_user)
   #   flags.get_flag("new_checkout")          # NO user arg — bound at construction
-  #   flags.get_experiment("price_test", { price: 9 })
+  #   flags.universe("checkout").assign       # NO user arg — bound at construction
   #
   # It is cheap: it delegates every evaluation to the single global engine built
   # by `Shipeasy.configure { … }`. It does NOT open its own HTTP connection,
@@ -62,11 +62,31 @@ module Shipeasy
       default
     end
 
-    def get_experiment(name, default_params, decode = nil)
-      @engine.get_experiment(name, @attributes, default_params, decode)
-    rescue StandardError => e
-      Shipeasy::Logging.error "[shipeasy] Client#get_experiment('#{name}') failed — returning safe default: #{e.message}"
-      Shipeasy::SDK::Eval::ExperimentResult.new(in_experiment: false, group: "control", params: default_params)
+    # Assign the bound user within a universe: `client.universe("checkout").assign`.
+    # A universe is a mutual-exclusion pool — the unit lands in at most one
+    # experiment. Returns a reusable handle whose `assign` takes NO user arg (the
+    # user is bound at construction) and forwards the bound attributes to the
+    # engine. `assign` auto-logs a single deduped exposure when enrolled and
+    # returns an Eval::Assignment (never raises).
+    def universe(name)
+      BoundUniverseHandle.new(@engine, name, @attributes)
+    end
+
+    # Returned by Client#universe. Binds the universe name AND the client's
+    # already-resolved attributes, so `assign` needs no user argument.
+    class BoundUniverseHandle
+      def initialize(engine, name, attributes)
+        @engine     = engine
+        @name       = name
+        @attributes = attributes
+      end
+
+      def assign
+        @engine.assign_universe(@name, @attributes)
+      rescue StandardError => e
+        Shipeasy::Logging.error "[shipeasy] Client#universe('#{@name}').assign failed — returning not-enrolled: #{e.message}"
+        Shipeasy::SDK::Eval::Assignment.new(nil, nil, {})
+      end
     end
 
     # Killswitches are not user-scoped; forwarded straight to the engine.
@@ -84,13 +104,6 @@ module Shipeasy
       Shipeasy::Logging.error "[shipeasy] Client#track('#{event_name}') failed: #{e.message}"
       nil
     end
-
-    def log_exposure(experiment_name)
-      @engine.log_exposure(@attributes, experiment_name)
-    rescue StandardError => e
-      Shipeasy::Logging.error "[shipeasy] Client#log_exposure('#{experiment_name}') failed: #{e.message}"
-      nil
-    end
   end
 
   # Raised by Shipeasy::Client when constructed before Shipeasy.configure.

data/lib/shipeasy/config.rb

@@ -30,8 +30,14 @@ module Shipeasy
     #   - private_attributes: attribute keys stripped from every outbound event
     #     before it leaves the process (they still drive targeting locally).
     #   - sticky_store: pin a user's experiment group across re-buckets.
+    #   - disable_internal_error_reporting (default false): opt out of the
+    #     SDK's self-monitoring channel. When the SDK's last-resort guard
+    #     swallows one of its OWN internal errors it normally ships a structured
+    #     see event to Shipeasy's own project (NOT yours) so the SDK team can
+    #     track SDK bugs; set true to disable that entirely.
     attr_accessor :env, :disable_telemetry, :telemetry_url,
-                  :private_attributes, :sticky_store
+                  :private_attributes, :sticky_store,
+                  :disable_internal_error_reporting
 
     # SDK-wide diagnostic verbosity for the leveled logger (Shipeasy::Logging).
     # One of :silent, :error, :warn (default), :info, :debug (strings accepted
@@ -69,12 +75,13 @@ module Shipeasy
                   :manifest_cache_ttl, :label_file_cache_ttl, :http_timeout
 
     def initialize
-      @base_url             = "https://edge.shipeasy.dev"
+      @base_url             = "https://api.shipeasy.ai"
       @attributes           = nil
       @init                 = true
       @poll                 = false
       @env                  = "prod"
       @disable_telemetry    = false
+      @disable_internal_error_reporting = false
       @telemetry_url        = nil
       @private_attributes   = nil
       @sticky_store         = nil
@@ -157,6 +164,7 @@ module Shipeasy
         private_attributes: cfg.private_attributes,
         sticky_store:       cfg.sticky_store,
         log_level:          cfg.log_level,
+        disable_internal_error_reporting: cfg.disable_internal_error_reporting,
       )
       @engine = engine
       # Capture +engine+ in the closure (not the @engine ivar, which a concurrent

data/lib/shipeasy/engine.rb

@@ -9,6 +9,7 @@ require_relative "sdk/telemetry"
 require_relative "sdk/anon_id"
 require_relative "sdk/sticky_store"
 require_relative "sdk/see"
+require_relative "sdk/internal_report"
 
 module Shipeasy
   # The heavyweight engine: owns the api key, HTTP transport, the blob cache,
@@ -29,12 +30,12 @@ module Shipeasy
       AnonId    = Shipeasy::SDK::AnonId
       See       = Shipeasy::SDK::See
 
-      DEFAULT_BASE_URL = "https://edge.shipeasy.dev"
+      DEFAULT_BASE_URL = "https://api.shipeasy.ai"
       # CDN origin serving the static loader scripts (/sdk/bootstrap.js,
       # /sdk/i18n/loader.js) — distinct from the edge API the blobs are fetched from.
       DEFAULT_CDN_BASE = "https://cdn.shipeasy.ai"
 
-      def initialize(api_key:, base_url: nil, env: "prod", disable_telemetry: false, telemetry_url: nil, test_mode: false, private_attributes: nil, sticky_store: nil, log_level: nil)
+      def initialize(api_key:, base_url: nil, env: "prod", disable_telemetry: false, telemetry_url: nil, test_mode: false, private_attributes: nil, sticky_store: nil, log_level: nil, disable_internal_error_reporting: false)
         # SDK-wide diagnostic verbosity. Set the leveled logger from the passed
         # level (default :warn; unknown falls back to :warn). The logger is
         # module-scoped, so the last-built engine wins — mirrors the TS SDK,
@@ -51,7 +52,7 @@ module Shipeasy
         # track(), where the listed keys are dropped from the props bag.
         @private_attributes = (private_attributes || []).map(&:to_s)
         # Pluggable sticky-bucketing store (doc 20 §2). Absent ⇒ deterministic.
-        # Threaded into get_experiment so an enrolled unit locks to its first
+        # Threaded into experiment eval so an enrolled unit locks to its first
         # assigned variant. Built-in: InMemoryStickyStore.
         @sticky_store = sticky_store
         # Test mode: no network, ever. init/init_once/track become no-ops and
@@ -88,6 +89,22 @@ module Shipeasy
         # see() structured error reporting. Per-process spam guard, bound here so
         # repeated reports of the same issue collapse to one send. See see.rb.
         @see_limiter = See::Limiter.new
+        # Auto-exposure dedup set: assign() logs a single exposure per
+        # (unit, experiment, group) so repeated assigns in one process don't spam
+        # /collect. Bounded — cleared when it grows past ~5000 keys.
+        @exposure_seen = {}
+        # Self-monitoring channel: when safe_run swallows one of the SDK's OWN
+        # internal errors, it also ships a see event to Shipeasy's own project
+        # (a baked-in destination, distinct from the consumer's see() path) so
+        # the SDK team can track SDK bugs across every app. Fire-and-forget,
+        # never raises. On by default; forced off in test mode (no network) and
+        # opt-out-able via disable_internal_error_reporting. Module-scoped, so
+        # the last-built engine wins — mirrors set_level / the TS reference.
+        Shipeasy::SDK::InternalReport.set_context(
+          side: "server",
+          sdk_version: Shipeasy::SDK::VERSION,
+          enabled: !test_mode && !disable_internal_error_reporting,
+        )
         # Register as the default client backing the module-level Shipeasy::SDK
         # .see/.see_violation funcs (last constructed wins — the server-SDK
         # analog of TS's shipeasy({key}) configure call).
@@ -283,48 +300,68 @@ module Shipeasy
         end
       end
 
-      def get_experiment(name, user, default_params, decode = nil)
-        safe_run("get_experiment('#{name}')", Eval::ExperimentResult.new(in_experiment: false, group: "control", params: default_params)) do
-          get_experiment_inner(name, user, default_params, decode)
-        end
-      end
-
-      def get_experiment_inner(name, user, default_params, decode = nil)
-        key = name.to_s
-        override = @mutex.synchronize { @exp_overrides[key] }
-        if override
-          params = override[:params]
-          params = decode.call(params) if decode
-          return Eval::ExperimentResult.new(
-            in_experiment: true,
-            group: override[:group],
-            params: params,
+      # Assign +user+ within +universe_name+. A universe is a mutual-exclusion
+      # pool, so a unit lands in AT MOST ONE experiment; the returned
+      # Eval::Assignment exposes the variant + resolved params and auto-logs a
+      # single exposure when enrolled. An un-enrolled unit still resolves get()
+      # to the universe defaults. Never raises. This is the sole experiment read
+      # path — there is no get_experiment (a caller asks a universe, not an
+      # experiment). Internal: the public surface is universe(name).assign(user).
+      def assign_universe(universe_name, user)
+        empty = Eval::Assignment.new(nil, nil, {})
+        safe_run("assign_universe('#{universe_name}')", empty) do
+          @telemetry.emit("experiment", universe_name)
+          u = with_anon_id(user)
+          flags_blob, exps_blob = @mutex.synchronize { [@flags_blob, @exps_blob] }
+
+          universe = exps_blob&.dig("universes", universe_name.to_s)
+          param_defaults = Eval.param_defaults_from_schema(
+            universe && (universe["param_schema"] || universe[:param_schema])
           )
+          not_enrolled = Eval::Assignment.new(nil, nil, param_defaults || {})
+          next not_enrolled unless exps_blob
+
+          # Candidate running experiments in this universe. Deterministic order:
+          # pool-slice offset asc (slices are disjoint so <=1 matches under
+          # pooling), then name. A universe-held-out or unallocated unit falls
+          # through to the defaults-only handle.
+          candidates = (exps_blob["experiments"] || {}).select do |_name, exp|
+            exp["universe"] == universe_name.to_s && exp["status"] == "running"
+          end.sort_by { |name, exp| [(exp["poolOffsetBp"] || 0), name] }
+
+          landed = nil
+          candidates.each do |name, exp|
+            result = eval_experiment(name, exp, u, flags_blob, exps_blob)
+            next unless result.in_experiment
+            post_exposure(u, name, result.group)
+            landed = Eval::Assignment.new(name, result.group, result.params || {})
+            break
+            # not enrolled: try the next candidate — under pooling only one slice
+            # can match, so the loop lands on the winner (or falls through).
+          end
+
+          landed || not_enrolled
         end
+      end
 
-        @telemetry.emit("experiment", name)
-        flags_blob, exps_blob = @mutex.synchronize { [@flags_blob, @exps_blob] }
-        exp = exps_blob&.dig("experiments", name)
-        result = Eval.eval_experiment(
-          exp, flags_blob, exps_blob, with_anon_id(user),
-          exp_name: name.to_s, sticky_store: @sticky_store,
-        )
-        result.params ||= default_params
+      # A reusable handle bound to one universe. +assign(user)+ picks the <=1
+      # experiment the unit is pooled into and auto-logs a single exposure. See
+      # assign_universe.
+      def universe(name)
+        UniverseHandle.new(self, name)
+      end
 
-        if result.in_experiment && decode
-          begin
-            result = Eval::ExperimentResult.new(
-              in_experiment: true,
-              group: result.group,
-              params: decode.call(result.params),
-            )
-          rescue => e
-            Shipeasy::Logging.warn "[shipeasy] get_experiment('#{name}') decode failed: #{e.message}"
-            return Eval::ExperimentResult.new(in_experiment: false, group: "control", params: default_params)
-          end
+      # Returned by Engine#universe. Binds a universe name so callers can reuse
+      # the handle: `engine.universe("checkout").assign(user)`.
+      class UniverseHandle
+        def initialize(engine, name)
+          @engine = engine
+          @name   = name
         end
 
-        result
+        def assign(user)
+          @engine.assign_universe(@name, user)
+        end
       end
 
       # Public hook for the bound Shipeasy::Client: normalise an attribute hash
@@ -363,9 +400,8 @@ module Shipeasy
       # for this SDK. No telemetry (a batch evaluate is not a per-flag exposure).
       def evaluate(user)
         u = with_anon_id(user)
-        flags_blob, exps_blob, flag_ov, config_ov, exp_ov, sticky = @mutex.synchronize do
-          [@flags_blob, @exps_blob, @flag_overrides.dup, @config_overrides.dup,
-           @exp_overrides.dup, @sticky_store]
+        flags_blob, exps_blob, flag_ov, config_ov = @mutex.synchronize do
+          [@flags_blob, @exps_blob, @flag_overrides.dup, @config_overrides.dup]
         end
 
         flags = {}
@@ -378,18 +414,30 @@ module Shipeasy
           configs[name] = config_ov.key?(name) ? config_ov[name] : entry["value"]
         end
 
+        # Per-experiment result carries the universe name; a top-level universes
+        # map exposes each universe's param defaults so the client can resolve
+        # universe(name).get() to a default even when the unit is not enrolled.
         experiments = {}
+        universes = {}
         (exps_blob&.dig("experiments") || {}).each do |name, exp|
-          if exp_ov.key?(name)
-            ov = exp_ov[name]
-            experiments[name] = { "inExperiment" => true, "group" => ov[:group], "params" => ov[:params] }
-            next
+          uni_name = exp["universe"]
+          unless universes.key?(uni_name)
+            uni = exps_blob&.dig("universes", uni_name)
+            universes[uni_name] = {
+              "defaults" => Eval.param_defaults_from_schema(uni && (uni["param_schema"] || uni[:param_schema])) || {},
+            }
           end
-          r = Eval.eval_experiment(exp, flags_blob, exps_blob, u, exp_name: name, sticky_store: sticky)
-          experiments[name] = { "inExperiment" => r.in_experiment, "group" => r.group, "params" => r.params }
+          r = eval_experiment(name, exp, u, flags_blob, exps_blob, emit_telemetry: false)
+          experiments[name] = {
+            "inExperiment" => r.in_experiment,
+            "group" => r.in_experiment ? r.group : "control",
+            "params" => r.in_experiment ? (r.params || {}) : {},
+            "universe" => uni_name,
+          }
         end
 
-        { "flags" => flags, "configs" => configs, "experiments" => experiments, "killswitches" => {} }
+        { "flags" => flags, "configs" => configs, "experiments" => experiments,
+          "killswitches" => {}, "universes" => universes }
       end
 
       # Return the cross-platform SSR bootstrap <script> tag for a request:
@@ -445,40 +493,6 @@ module Shipeasy
         end
       end
 
-      # Emit an exposure event for an experiment at the server-side decision
-      # point (parity with the browser's auto-exposure). The server is stateless
-      # and never auto-logs, so call this when you actually present the
-      # treatment. Re-evaluates the experiment for the user (a bare user_id
-      # string is wrapped as { "user_id" => id }); if enrolled, POSTs a single
-      # exposure to /collect. No-op in test mode or when the user isn't enrolled.
-      def log_exposure(user_or_user_id, experiment_name)
-        safe_run("log_exposure('#{experiment_name}')", nil) do
-          next if @test_mode
-
-          user = user_or_user_id.is_a?(Hash) ? user_or_user_id : { "user_id" => user_or_user_id.to_s }
-          result = get_experiment(experiment_name, user, {})
-          next unless result.in_experiment
-
-          u = user.transform_keys(&:to_s)
-          payload = JSON.generate({
-            events: [{
-              type: "exposure",
-              experiment: experiment_name.to_s,
-              group: result.group,
-              user_id: (u["user_id"] || u["anonymous_id"]).to_s,
-              ts: (Time.now.to_f * 1000).to_i,
-            }],
-          })
-
-          Thread.new do
-            post("/collect", payload)
-          rescue => e
-            Shipeasy::Logging.warn "[shipeasy] log_exposure failed: #{e.message}"
-          end
-          nil
-        end
-      end
-
       # ---- see() structured error reporting -------------------------------
 
       # Report a caught exception (or thrown non-exception). Fire-and-forget;
@@ -507,8 +521,8 @@ module Shipeasy
       private
 
       # Last-resort guard that makes a public RUNTIME method (get_flag /
-      # get_config / get_experiment / get_killswitch / track / log_exposure)
-      # unable to raise into product code, even if an internal invariant is
+      # get_config / assign_universe / get_killswitch / track) unable to raise
+      # into product code, even if an internal invariant is
       # violated. Runs the block; on any StandardError it logs at :error and
       # returns +fallback+ (the method's documented safe default). +label+ names
       # the method for the log line.
@@ -516,9 +530,87 @@ module Shipeasy
         yield
       rescue StandardError => e
         Shipeasy::Logging.error "[shipeasy] #{label} failed — returning safe default: #{e.message}"
+        # A caught error here is by definition "on our end" — an internal SDK
+        # failure, not the caller's — so in addition to logging locally it is
+        # reported to Shipeasy's own project via the self-monitoring channel
+        # (fire-and-forget, never raises). The label's stable stem (e.g.
+        # "get_flag" from "get_flag('new_checkout')") is the issue subject, so
+        # occurrences of the same bug dedupe regardless of the resource name.
+        Shipeasy::SDK::InternalReport.report(internal_subject(label), e)
         fallback
       end
 
+      # The stable subject for an internal-error report: strip the variable
+      # "('resource')" argument off a safe_run label so the fingerprint carries
+      # no variable data and identical bugs dedupe into one issue.
+      def internal_subject(label)
+        label.to_s.sub(/\(.*\)\z/, "")
+      end
+
+      # Evaluate one experiment by name for +user+ — override -> full classify
+      # pipeline (targeting -> universe holdout -> holdout gate -> sticky ->
+      # allocation -> group), merging the universe defaults under the assigned
+      # variant. Returns an Eval::ExperimentResult. Reused by assign_universe and
+      # the SSR evaluate() bootstrap (keyed by experiment name). Emits the
+      # per-experiment telemetry beacon exactly once (never on the override
+      # short-circuit), unless +emit_telemetry+ is false (the batch evaluate()
+      # path is not a per-experiment exposure). +user+ is expected pre-normalised
+      # (with_anon_id).
+      def eval_experiment(name, exp, user, flags_blob, exps_blob, emit_telemetry: true)
+        key = name.to_s
+        override = @mutex.synchronize { @exp_overrides[key] }
+        if override
+          universe = exps_blob&.dig("universes", exp && exp["universe"])
+          param_defaults = Eval.param_defaults_from_schema(
+            universe && (universe["param_schema"] || universe[:param_schema])
+          )
+          return Eval::ExperimentResult.new(
+            in_experiment: true,
+            group: override[:group],
+            params: Eval.merge_params(param_defaults, override[:params]),
+          )
+        end
+
+        @telemetry.emit("experiment", name) if emit_telemetry
+        Eval.eval_experiment(
+          exp, flags_blob, exps_blob, user,
+          exp_name: key, sticky_store: @sticky_store,
+        )
+      end
+
+      # POST a single exposure for an enrolled (user, experiment, group). Deduped
+      # per process (bounded set) so repeated assign() calls in one server don't
+      # spam /collect. Fire-and-forget; no-op in test mode. This is how
+      # assign_universe auto-logs — the browser's auto-exposure parity for SSR.
+      def post_exposure(user, experiment, group)
+        return if @test_mode
+        u = user.transform_keys(&:to_s)
+        uid = u["user_id"] || u["anonymous_id"]
+        dedup_key = "#{uid}:#{experiment}:#{group}"
+        @mutex.synchronize do
+          return if @exposure_seen.key?(dedup_key)
+          @exposure_seen.clear if @exposure_seen.size > 5000
+          @exposure_seen[dedup_key] = true
+        end
+
+        payload = JSON.generate({
+          events: [{
+            type: "exposure",
+            experiment: experiment.to_s,
+            group: group,
+            user_id: uid.to_s,
+            ts: (Time.now.to_f * 1000).to_i,
+          }],
+        })
+
+        Thread.new do
+          post("/collect", payload)
+        rescue => e
+          Shipeasy::Logging.warn "[shipeasy] exposure send failed: #{e.message}"
+        end
+        nil
+      end
+
       # Build the wire event and fire-and-forget POST it to /collect. No-op in
       # test mode (mirrors track). Spam-guarded. Never raises into caller code.
       def dispatch_see(built)

data/lib/shipeasy/logging.rb

@@ -3,7 +3,7 @@
 # Every diagnostic the SDK emits from a *caught* error goes through here, so a
 # single `log_level` config option (default :warn) controls the SDK's stderr
 # output. The contract for the SDK's public RUNTIME methods (get_flag,
-# get_config, get_experiment, get_killswitch, track, log_exposure, see, …) is
+# get_config, universe(...).assign, get_killswitch, track, see, …) is
 # that they NEVER raise into product code — so logging itself is best-effort
 # too: a broken/throwing $stderr can never take down a flag read.
 #

data/lib/shipeasy/sdk/eval.rb

@@ -92,6 +92,26 @@ module Shipeasy
 
       ExperimentResult = Struct.new(:in_experiment, :group, :params, keyword_init: true)
 
+      # Flatten a universe param schema (`[{ "name", "type", "default" }, ...]`)
+      # to a plain `name => default` map — the defaults `assign()` layers under a
+      # variant's override map. Returns nil for a null/empty schema so the merge
+      # short-circuits. Mirrors the TS reference / @shipeasy/core.
+      def self.param_defaults_from_schema(schema)
+        return nil if schema.nil? || schema.empty?
+        schema.each_with_object({}) do |p, h|
+          name = p["name"] || p[:name]
+          h[name] = p.key?("default") ? p["default"] : p[:default]
+        end
+      end
+
+      # `universeDefaults ⊕ variantOverride` — a variant inherits every universe
+      # default it doesn't explicitly override. A nil defaults map short-circuits
+      # to the variant params (dup'd) alone.
+      def self.merge_params(param_defaults, group_params)
+        gp = group_params || {}
+        param_defaults ? param_defaults.merge(gp) : gp.dup
+      end
+
       # exp_name + sticky_store are optional so existing callers stay deterministic.
       # When a sticky_store is passed, an enrolled unit whose stored salt prefix
       # still matches skips the allocation gate (so a shrinking allocation keeps
@@ -99,8 +119,23 @@ module Shipeasy
       # pick is persisted via store.set; a salt mismatch / missing stored group
       # falls through to re-bucket + overwrite. Mirrors the TS reference
       # (doc 20 §2). exp_name is the key under which the entry is stored.
+      #
+      # Pooling / holdout-gate / reserved-headroom / universe param-default merge
+      # (doc 20 §B) are layered in here so both the low-level parity path and the
+      # universe assign() path share ONE classify. The added steps are all guarded
+      # by presence checks, so a legacy blob (no hashVersion/pool/reserved) behaves
+      # exactly as before.
       def self.eval_experiment(exp, flags_blob, exps_blob, user, exp_name: nil, sticky_store: nil)
+        universe_name  = exp && exp["universe"]
+        universe       = exps_blob&.dig("universes", universe_name)
+        param_defaults = param_defaults_from_schema(universe && (universe["param_schema"] || universe[:param_schema]))
+
         not_in = ExperimentResult.new(in_experiment: false, group: "control", params: nil)
+        as_group = lambda do |g|
+          ExperimentResult.new(
+            in_experiment: true, group: g["name"], params: merge_params(param_defaults, g["params"]),
+          )
+        end
 
         return not_in unless exp && exp["status"] == "running"
 
@@ -114,12 +149,22 @@ module Shipeasy
         uid = pick_identifier(user, bucket_by)
         return not_in unless uid
 
-        universe_name = exp["universe"]
-        universe = exps_blob&.dig("universes", universe_name)
+        # One segment in the universe's shared [0, 10000) hash space. The holdout
+        # carve-out AND every experiment's pool slice are disjoint ranges of THIS
+        # segment — that's what makes "held out / taken / free" a real partition.
+        universe_seg = murmur3("#{universe_name}:#{uid}") % 10000
+
         holdout = universe&.dig("holdout_range")
         if holdout
-          seg = murmur3("#{universe_name}:#{uid}") % 10000
-          return not_in if seg >= holdout[0] && seg <= holdout[1]
+          return not_in if universe_seg >= holdout[0] && universe_seg <= holdout[1]
+        end
+
+        # Holdout gate: a passing gate holds the unit out of every experiment in
+        # the universe (mirrors the universe carve-out, but gate-driven).
+        holdout_gate = exp["holdoutGate"]
+        if holdout_gate && !holdout_gate.to_s.empty?
+          gate = flags_blob&.dig("gates", holdout_gate)
+          return not_in if gate && eval_gate(gate, user)
         end
 
         salt          = exp["salt"]
@@ -134,24 +179,87 @@ module Shipeasy
           entry = (sticky_store.get(uid) || {})[exp_name]
           if entry && entry["s"] == salt8
             g = groups.find { |x| x["name"] == entry["g"] }
-            return ExperimentResult.new(in_experiment: true, group: g["name"], params: g["params"]) if g
+            return as_group.call(g) if g
           end
         end
 
-        return not_in if murmur3("#{salt}:alloc:#{uid}") % 10000 >= allocation_pct
+        # Allocation. Pooled (hashVersion >= 2 with a slice) gives real mutual
+        # exclusion: the unit's universe segment must fall in the claimed range.
+        # Legacy falls back to an independent per-experiment salt so siblings
+        # overlap freely (the existing parity path).
+        hash_version = exp["hashVersion"] || exp[:hashVersion] || 1
+        pool_offset  = exp["poolOffsetBp"] || exp[:poolOffsetBp]
+        pool_size    = exp["poolSizeBp"] || exp[:poolSizeBp]
+        pooled       = hash_version >= 2 && !pool_offset.nil? && !pool_size.nil? && pool_size > 0
+        if pooled
+          lo = pool_offset
+          hi = pool_offset + pool_size
+          return not_in if universe_seg < lo || universe_seg >= hi
+        else
+          return not_in if murmur3("#{salt}:alloc:#{uid}") % 10000 >= allocation_pct
+        end
 
+        # Group split over [0, usable) where usable = 10000 - reserved; a unit in
+        # the reserved tail is left unassigned so an appended variant can absorb it.
+        reserved = (exp["reservedHeadroomBp"] || exp[:reservedHeadroomBp] || 0)
+        reserved = 0 if reserved < 0
+        reserved = 10000 if reserved > 10000
+        usable = 10000 - reserved
         group_hash = murmur3("#{salt}:group:#{uid}") % 10000
+        return not_in if group_hash >= usable
+
         cumulative = 0
         groups.each_with_index do |g, i|
           cumulative += g["weight"]
           if group_hash < cumulative || i == groups.length - 1
             sticky_store.set(uid, exp_name, { "g" => g["name"], "s" => salt8 }) if sticky_store && exp_name
-            return ExperimentResult.new(in_experiment: true, group: g["name"], params: g["params"])
+            return as_group.call(g)
           end
         end
 
         not_in
       end
+
+      # The result of `universe(name).assign(user)` — a unit's standing in a
+      # universe (a mutual-exclusion pool, so it lands in at most one experiment).
+      # Never raises: an un-enrolled unit still resolves `get` to the universe
+      # defaults (or the caller's fallback). Reading is side-effect free — the
+      # single exposure is logged once by assign() when the unit is enrolled.
+      class Assignment
+        # The experiment the unit landed in, or nil when not enrolled.
+        attr_reader :name
+        # The assigned variant/group name, or nil when not enrolled.
+        attr_reader :group
+
+        # +params+ is already merged (universeDefaults ⊕ variantOverride) when
+        # enrolled; defaults-only (or {}) when not.
+        def initialize(name, group, params)
+          @name   = name
+          @group  = group
+          @params = params || {}
+        end
+
+        # True iff the unit is enrolled in an experiment in this universe.
+        def enrolled?
+          !@group.nil?
+        end
+
+        # Read a resolved param: the assigned variant's override, else the
+        # universe default, else +fallback+. Works even when not enrolled (the
+        # variant layer is absent, so you get universeDefault ?? fallback).
+        # Looks up both string and symbol keys.
+        def get(field, fallback = nil)
+          if @params.key?(field)
+            @params[field]
+          elsif field.respond_to?(:to_s) && @params.key?(field.to_s)
+            @params[field.to_s]
+          elsif field.respond_to?(:to_sym) && @params.key?(field.to_sym)
+            @params[field.to_sym]
+          else
+            fallback
+          end
+        end
+      end
     end
   end
 end

data/lib/shipeasy/sdk/internal_report.rb

@@ -0,0 +1,154 @@
+# Internal self-monitoring channel — SDK bugs that are "on our end".
+#
+# When the SDK swallows one of its OWN internal errors (the `Engine#safe_run`
+# last-resort guard in engine.rb, which keeps a get_flag/get_config/… from
+# raising into product code even when an internal invariant is violated), it
+# ALSO ships a structured see event here — to Shipeasy's OWN project, NOT the
+# consumer's — so the SDK team can track SDK-internal failures across every app
+# the SDK runs in.
+#
+# This is deliberately distinct from the customer-facing `see()` path
+# (Shipeasy::SDK.see / Engine#see), which authenticates with the consumer's key
+# and lands in the consumer's dashboard. Internal errors must never pollute a
+# customer's Errors tab, and the SDK team must see them centrally — so this
+# channel has its own baked-in destination + credential.
+#
+# Guarantees (identical to telemetry/see): fire-and-forget, never blocks, never
+# raises into product code, deduped/rate-limited. A failed send is swallowed
+# silently — it must never log (that would risk recursion through safe_run).
+
+require "net/http"
+require "uri"
+require "json"
+require "thread"
+require_relative "see"
+require_relative "version"
+
+module Shipeasy
+  module SDK
+    module InternalReport
+      # ---- Baked-in destination ----
+      #
+      # The main Shipeasy project (`.shipeasy` project_id
+      # e976b15e-3ccc-44d3-821d-87f06d5a0e43). The credential is a PUBLIC client
+      # key — the same class of credential already embedded verbatim in every
+      # browser bundle that ships the client SDK, and mirroring how the CLI bakes
+      # Shipeasy's own public key for setup-bug self-reporting — so baking it into
+      # the published gem is safe. `/collect` treats it as a write-only ingest
+      # key; it grants no read access. The canonical ingest host is
+      # api.shipeasy.ai (the SDK default base_url), which routes /collect to the
+      # edge worker.
+      INGEST_URL = "https://api.shipeasy.ai/collect".freeze
+
+      # Sentinel used until the real key is minted + baked. While INGEST_KEY is
+      # still the placeholder the channel stays fully inert (see .report), so a
+      # gem that ships before the key is provisioned never fires doomed requests.
+      # Mint the key with:
+      #   shipeasy keys create --type client --env prod \
+      #     --name "SDK internal error self-reporting" --scopes events:write
+      # then replace the INGEST_KEY assignment below with the returned value.
+      PLACEHOLDER_KEY = "sdk_client_REPLACE_WITH_SHIPEASY_INTERNAL_ERROR_KEY".freeze
+
+      # The baked-in ingest credential. Swap the placeholder for the real minted
+      # key here (this is the ONLY line to change when the key is provisioned).
+      INGEST_KEY = "sdk_client_00bd4608a03e4084922978f9522614d5"
+
+      # Stable consequence. The `label` (the safe_run operation name, e.g.
+      # "flags.get") is the subject; the outcome is fixed. Both are constant per
+      # operation — no variable data — so occurrences of the same internal bug
+      # fold into one issue on our dashboard (fingerprint = error_type +
+      # normalized message + top stack + subject|outcome). `sdk` marks which
+      # language SDK reported it.
+      OUTCOME = "returned a safe default".freeze
+      SDK_ID  = "ruby".freeze
+
+      class << self
+        # True once a real key has been baked in (not the placeholder sentinel).
+        def key_configured?(key = @ingest_key || INGEST_KEY)
+          !key.nil? && !key.empty? && key != PLACEHOLDER_KEY
+        end
+
+        # Wire the self-monitoring channel. Called from Engine#initialize with the
+        # bundle's side + version. `enabled` defaults on; it is forced off in test
+        # mode (no network) and when the caller opts out via
+        # disable_internal_error_reporting.
+        def set_context(side:, sdk_version:, enabled: true)
+          @side        = side
+          @sdk_version = sdk_version
+          @enabled     = enabled != false
+          @limiter   ||= See::Limiter.new
+        end
+
+        # Report an SDK-internal error to Shipeasy's own project. Called from
+        # Engine#safe_run's rescue. `label` is the swallowed operation (e.g.
+        # "flags.get") and becomes the stable issue subject. Never raises.
+        def report(label, err)
+          return unless @enabled
+          key = @ingest_key || INGEST_KEY
+          return unless key_configured?(key)
+
+          ev = See.build_event(
+            err,
+            label.to_s,
+            OUTCOME,
+            { "sdk" => SDK_ID },
+            sdk_version: @sdk_version || Shipeasy::SDK::VERSION,
+            env: nil,
+          )
+          # Internal reports carry only the SDK-side context — never a consumer's
+          # env or url — so a customer's config can't leak into our project.
+          ev["side"] = @side || "server"
+
+          limiter = (@limiter ||= See::Limiter.new)
+          return unless limiter.should_send?(ev)
+
+          send_event(key, JSON.generate({ events: [ev] }))
+        rescue StandardError
+          # Self-reporting must never raise into product code.
+          nil
+        end
+
+        private
+
+        # Fire-and-forget POST to the baked-in ingest on a background thread.
+        # Isolated so specs can intercept it without real network. A failed send
+        # is swallowed silently — it must never log (that would risk recursion
+        # through safe_run).
+        def send_event(key, body)
+          Thread.new do
+            begin
+              uri  = URI.parse(INGEST_URL)
+              http = Net::HTTP.new(uri.host, uri.port)
+              http.use_ssl      = (uri.scheme == "https")
+              http.open_timeout = 2
+              http.read_timeout = 2
+              http.post(uri.request_uri, body, { "X-SDK-Key" => key, "Content-Type" => "text/plain" })
+            rescue StandardError
+              # self-reporting must never surface a network error
+            end
+          end
+        end
+
+        # ---- Test seams ----
+
+        public
+
+        # Reset module state (context + rate limiter + key override) so a spec
+        # starts from a clean, inert channel.
+        def reset_for_test!
+          @side        = nil
+          @sdk_version = nil
+          @enabled     = nil
+          @limiter     = See::Limiter.new
+          @ingest_key  = nil
+        end
+
+        # Stand in a real-looking key so specs can exercise the send path without
+        # the (deliberately inert) placeholder blocking it.
+        def set_ingest_key_for_test(key)
+          @ingest_key = key
+        end
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/version.rb

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "2.4.0"
+    VERSION = "3.0.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shipeasy-sdk
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Shipeasy, Inc.
@@ -143,6 +143,7 @@ files:
 - lib/shipeasy/logging.rb
 - lib/shipeasy/sdk/anon_id.rb
 - lib/shipeasy/sdk/eval.rb
+- lib/shipeasy/sdk/internal_report.rb
 - lib/shipeasy/sdk/murmur3.rb
 - lib/shipeasy/sdk/openfeature.rb
 - lib/shipeasy/sdk/rack_middleware.rb