smplkit 3.0.95 → 3.0.97

data/lib/smplkit/flags/client.rb

@@ -1,12 +1,46 @@
 # frozen_string_literal: true
 
-require "concurrent"
 require "json"
 require "digest"
 
+# The Smpl Flags client — one unified +FlagsClient+.
+#
+# Smpl Flags has two surfaces on a single client, mirroring how the config,
+# audit, and jobs clients expose their full surface from one class:
+#
+# * *CRUD surface* — pure CRUD, no live connection: +new_boolean_flag+ /
+#   +new_string_flag+ / +new_number_flag+ / +new_json_flag+ constructors, +get+
+#   / +list+ / +delete+ CRUD, and the flag-declaration discovery buffer
+#   (+register+ / +flush+ / +flush_sync+ / +pending_count+). The client owns the
+#   discovery buffer directly.
+# * *Live surface* — lazily connects to your running service on first use: the
+#   typed handle declarations (+boolean_flag+ / +string_flag+ / +number_flag+ /
+#   +json_flag+) whose +.get+ evaluates against the cached definitions, plus
+#   +refresh+ / +stats+ / +on_change+. The first live call transparently flushes
+#   discovery, fetches all flag definitions into the local cache, and opens the
+#   live-updates WebSocket — no explicit install step.
+#
+# The client supports two construction shapes:
+#
+# * *Wired* into +Smplkit::Client+ — borrows the parent's flags transport for
+#   both runtime fetch and CRUD, the parent's shared WebSocket for the live
+#   channel, and +client.platform.contexts+ for evaluation-context
+#   registration. This is the common path.
+# * *Standalone* — +FlagsClient.new(api_key: ..., base_url: ..., ...)+ builds
+#   and owns its own flags transport and a contexts client (against its own app
+#   transport), and on first live use opens and owns its own WebSocket. +close+
+#   tears down only the owned transports and owned WebSocket.
 module Smplkit
   module Flags
     # Describes a flag definition change. Frozen — fields are set at construction.
+    #
+    # @!attribute [r] id
+    #   @return [String] id of the flag whose definition changed.
+    # @!attribute [r] source
+    #   @return [String] origin of the change (e.g. +"websocket"+ for a live
+    #     update or +"manual"+ for a refresh).
+    # @!attribute [r] deleted
+    #   @return [Boolean] whether the change was a deletion of the flag.
     class FlagChangeEvent
       attr_reader :id, :source, :deleted
 
@@ -28,6 +62,8 @@ module Smplkit
     end
 
     # Thread-safe LRU resolution cache with hit/miss stats.
+    #
+    # @api private
     class ResolutionCache
       DEFAULT_MAX_SIZE = 10_000
 
@@ -41,6 +77,7 @@ module Smplkit
         @cache_misses = 0
       end
 
+      # Return [hit, value]. Moves the key to end on hit.
       def get(cache_key)
         @lock.synchronize do
           if @cache.key?(cache_key)
@@ -69,106 +106,385 @@ module Smplkit
     end
 
     # Evaluation statistics for the flags runtime.
+    #
+    # @!attribute [r] cache_hits
+    #   @return [Integer] number of flag evaluations served from the local cache.
+    # @!attribute [r] cache_misses
+    #   @return [Integer] number of flag evaluations that missed the cache and
+    #     were evaluated from the flag definitions.
     FlagStats = Struct.new(:cache_hits, :cache_misses, keyword_init: true)
 
-    # Synchronous flags runtime namespace.
+    # Convert a list of Context objects to the nested evaluation dict.
     #
-    # Obtained via +Smplkit::Client#flags+. Exposes typed handles
-    # (+boolean_flag+/+string_flag+/+number_flag+/+json_flag+) and runtime
-    # control (+refresh+, +stats+, +on_change+). CRUD has moved to
-    # +mgmt.flags.*+. Per-request context is set via
-    # +client.set_context([...])+.
-    class FlagsClient
-      INITIAL_START_RETRY_DELAY = 1.0
-      MAX_START_RETRY_DELAY = 60.0
+    # @api private
+    def self.contexts_to_eval_dict(contexts)
+      contexts.to_h { |ctx| [ctx.type, ctx.to_eval_hash] }
+    end
+
+    # Compute a stable hash for a context evaluation dict.
+    #
+    # @api private
+    def self.hash_context(eval_dict)
+      Digest::MD5.hexdigest(JSON.generate(deep_sort(eval_dict)))
+    end
+
+    # @api private
+    def self.deep_sort(value)
+      case value
+      when Hash
+        value.keys.sort_by(&:to_s).to_h { |k| [k, deep_sort(value[k])] }
+      when Array
+        value.map { |v| deep_sort(v) }
+      else
+        value
+      end
+    end
+
+    # Build standalone flags + app transports and resolve the app base URL.
+    #
+    # +base_url+/+api_key+ are used directly when supplied (the path a top-level
+    # client takes after it has already resolved them); otherwise the management
+    # config resolver fills in whatever is missing (+~/.smplkit+ / env vars /
+    # defaults). The app transport backs the standalone contexts client
+    # (evaluation-context registration); the app base URL is returned so a
+    # standalone client can open its own WebSocket against the event gateway.
+    #
+    # @api private
+    def self.flags_transport(api_key:, base_url:, profile:, base_domain:, scheme:, debug:, extra_headers:)
+      cfg = ConfigResolution.resolve_client_config(
+        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme, debug: debug
+      )
+      resolved_key = api_key.nil? ? cfg.api_key : api_key
+      merged = {}
+      merged.merge!(cfg.extra_headers || {})
+      merged.merge!(extra_headers || {})
+      tcfg = ConfigResolution::ResolvedClientConfig.new(
+        api_key: resolved_key, base_domain: cfg.base_domain, scheme: cfg.scheme,
+        debug: cfg.debug, extra_headers: merged
+      )
+      app_url = ConfigResolution.service_url(cfg.scheme, "app", cfg.base_domain)
+      flags_http = Transport.build_api_client(SmplkitGeneratedClient::Flags, "flags", tcfg, base_url: base_url)
+      app_http = Transport.build_api_client(SmplkitGeneratedClient::App, "app", tcfg)
+      [flags_http, app_http, app_url, resolved_key]
+    end
 
-      def initialize(parent, manage:, metrics:, flags_base_url:, app_base_url:)
+    # The Smpl Flags client (sync).
+    #
+    # One client exposes the full surface, reachable as +client.flags+
+    # (+Smplkit::Client+) or constructed directly:
+    #
+    #   flags = Smplkit::FlagsClient.new(environment: "production")
+    #   new_flag = flags.new_boolean_flag("beta", default: false)
+    #   new_flag.save
+    #   beta = flags.boolean_flag("beta", default: false)
+    #   beta.get # => ...
+    #
+    # The CRUD surface (+new_*+ / +get+ / +list+ / +delete+ and discovery)
+    # is pure CRUD. The live surface (+boolean_flag+ / +string_flag+ /
+    # +number_flag+ / +json_flag+ / +refresh+ / +stats+ / +on_change+) connects
+    # lazily on first use — the first call flushes discovery, fetches all flag
+    # definitions into the local cache, and opens the live-updates WebSocket. No
+    # explicit install step is required.
+    class FlagsClient
+      def initialize(api_key = nil, environment: nil, base_url: nil, profile: nil,
+                     base_domain: nil, scheme: nil, debug: nil, extra_headers: nil,
+                     parent: nil, transport: nil, contexts: nil, metrics: nil)
         @parent = parent
-        @manage = manage
         @metrics = metrics
-        @service = parent._service
-        @environment = parent._environment
-        @flags_base_url = flags_base_url
-        @app_base_url = app_base_url
+        @environment = parent.nil? ? environment : parent._environment
+        @service = parent&._service
+        @standalone_api_key = nil
+        if transport.nil?
+          @flags_http, app_http, @app_base_url, @standalone_api_key = Flags.flags_transport(
+            api_key: api_key, base_url: base_url, profile: profile,
+            base_domain: base_domain, scheme: scheme, debug: debug, extra_headers: extra_headers
+          )
+          # Standalone: build our own contexts client (and own its app transport).
+          @contexts = Platform::ContextsClient.new(app_http, ContextRegistrationBuffer.new)
+        else
+          @flags_http = transport
+          @app_base_url = nil
+          # Wired: borrow client.platform.contexts as the evaluation-context
+          # registration seam.
+          @contexts = contexts
+        end
+        @api = SmplkitGeneratedClient::Flags::FlagsApi.new(@flags_http)
+
+        # Discovery buffer is owned by this client (no management delegation).
+        @buffer = FlagRegistrationBuffer.new
 
+        # Live-surface state.
         @flag_store = {}
         @connected = false
         @ws_subscribed = false
-        @next_start_attempt_at = 0.0
-        @start_retry_delay = INITIAL_START_RETRY_DELAY
         @cache = ResolutionCache.new
         @handles = {}
         @global_listeners = []
         @key_listeners = Hash.new { |h, k| h[k] = [] }
         @ws_manager = nil
+        @owns_ws = false
         @lock = Mutex.new
       end
 
-      def boolean_flag(id, default:)
-        register_handle(BooleanFlag, id, "BOOLEAN", default)
+      # ----------------------------------------------------------------
+      # Management surface: CRUD (no live connection)
+      # ----------------------------------------------------------------
+
+      # Return a new unsaved boolean +BooleanFlag+. Call +save+ to persist.
+      #
+      # @param id [String] stable flag identifier, unique per account.
+      # @param default [Boolean] value served when no environment override or
+      #   rule applies.
+      # @param name [String, nil] human-readable display name; defaults to a
+      #   title-cased form of +id+.
+      # @param description [String, nil] optional free-text description of the flag.
+      # @return [BooleanFlag] an unsaved flag; call +save+ to persist it.
+      def new_boolean_flag(id, default:, name: nil, description: nil)
+        BooleanFlag.new(
+          self, id: id, name: name || Smplkit::Helpers.key_to_display_name(id),
+                type: "BOOLEAN", default: default,
+                values: [FlagValue.new(name: "True", value: true), FlagValue.new(name: "False", value: false)],
+                description: description
+        )
+      end
+
+      # Return a new unsaved string +StringFlag+. Call +save+ to persist.
+      #
+      # @param id [String] stable flag identifier, unique per account.
+      # @param default [String] value served when no environment override or
+      #   rule applies.
+      # @param name [String, nil] human-readable display name; defaults to a
+      #   title-cased form of +id+.
+      # @param description [String, nil] optional free-text description of the flag.
+      # @param values [Array<FlagValue>, nil] optional list of allowed values
+      #   constraining what the flag may serve; when omitted the flag is
+      #   unconstrained.
+      # @return [StringFlag] an unsaved flag; call +save+ to persist it.
+      def new_string_flag(id, default:, name: nil, description: nil, values: nil)
+        StringFlag.new(
+          self, id: id, name: name || Smplkit::Helpers.key_to_display_name(id),
+                type: "STRING", default: default, values: values, description: description
+        )
+      end
+
+      # Return a new unsaved numeric +NumberFlag+. Call +save+ to persist.
+      #
+      # @param id [String] stable flag identifier, unique per account.
+      # @param default [Numeric] value served when no environment override or
+      #   rule applies.
+      # @param name [String, nil] human-readable display name; defaults to a
+      #   title-cased form of +id+.
+      # @param description [String, nil] optional free-text description of the flag.
+      # @param values [Array<FlagValue>, nil] optional list of allowed values
+      #   constraining what the flag may serve; when omitted the flag is
+      #   unconstrained.
+      # @return [NumberFlag] an unsaved flag; call +save+ to persist it.
+      def new_number_flag(id, default:, name: nil, description: nil, values: nil)
+        NumberFlag.new(
+          self, id: id, name: name || Smplkit::Helpers.key_to_display_name(id),
+                type: "NUMERIC", default: default, values: values, description: description
+        )
+      end
+
+      # Return a new unsaved JSON +JsonFlag+. Call +save+ to persist.
+      #
+      # @param id [String] stable flag identifier, unique per account.
+      # @param default [Hash] value served when no environment override or
+      #   rule applies.
+      # @param name [String, nil] human-readable display name; defaults to a
+      #   title-cased form of +id+.
+      # @param description [String, nil] optional free-text description of the flag.
+      # @param values [Array<FlagValue>, nil] optional list of allowed values
+      #   constraining what the flag may serve; when omitted the flag is
+      #   unconstrained.
+      # @return [JsonFlag] an unsaved flag; call +save+ to persist it.
+      def new_json_flag(id, default:, name: nil, description: nil, values: nil)
+        JsonFlag.new(
+          self, id: id, name: name || Smplkit::Helpers.key_to_display_name(id),
+                type: "JSON", default: default, values: values, description: description
+        )
+      end
+
+      # Fetch the editable +Flag+ resource by id.
+      #
+      # @param id [String] identifier of the flag to fetch.
+      # @return [Flag] the flag, ready to mutate and +save+.
+      # @raise [Smplkit::NotFoundError] no flag with that id exists for the account.
+      def get(id)
+        response = ApiSupport::ErrorMapping.call { @api.get_flag(id) }
+        model_from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
-      def string_flag(id, default:)
-        register_handle(StringFlag, id, "STRING", default)
+      # List flags for the authenticated account.
+      #
+      # @param page_number [Integer, nil] 1-based page index to fetch; when
+      #   omitted the server default applies.
+      # @param page_size [Integer, nil] number of flags per page; when omitted
+      #   the server default applies.
+      # @return [Array<Flag>] the flags on the requested page.
+      def list(page_number: nil, page_size: nil)
+        opts = {}
+        opts[:page_number] = page_number unless page_number.nil?
+        opts[:page_size] = page_size unless page_size.nil?
+        response = ApiSupport::ErrorMapping.call { @api.list_flags(opts) }
+        (response.data || []).map { |r| model_from_resource(ApiSupport::ResourceShim.from_model(r)) }
+      end
+
+      # Delete a flag by id.
+      #
+      # @param id [String] identifier of the flag to delete.
+      # @return [void]
+      # @raise [Smplkit::NotFoundError] no flag with that id exists for the account.
+      def delete(id)
+        ApiSupport::ErrorMapping.call { @api.delete_flag(id) }
+        nil
       end
 
-      def number_flag(id, default:)
-        register_handle(NumberFlag, id, "NUMERIC", default)
+      def _create_flag(flag)
+        response = ApiSupport::ErrorMapping.call { @api.create_flag(flag_body(flag)) }
+        model_from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
-      def json_flag(id, default:)
-        register_handle(JsonFlag, id, "JSON", default)
+      def _update_flag(flag)
+        response = ApiSupport::ErrorMapping.call { @api.update_flag(flag.id, flag_body(flag)) }
+        model_from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
-      # Eagerly initialize the flags subclient.
+      # ----------------------------------------------------------------
+      # Management surface: discovery buffer (owned directly)
+      # ----------------------------------------------------------------
+
+      # Buffer flag declarations for bulk-discovery upload; optionally flush now.
       #
-      # Flushes any pending flag-declaration buffer, fetches all flag
-      # definitions, opens the shared WebSocket and subscribes to
-      # +flag_changed+ / +flag_deleted+ / +flags_changed+ events.
+      # @param items [FlagDeclaration, Array<FlagDeclaration>] a single
+      #   declaration or an array of them to queue.
+      # @param flush [Boolean] when true, send the buffered declarations
+      #   immediately via +flush+ before returning. When false (the default),
+      #   they stay buffered and are sent on the next flush — automatic once the
+      #   buffer reaches its batch size, or on the first live call.
+      # @return [void]
+      def register(items, flush: false)
+        batch = items.is_a?(Array) ? items : [items]
+        batch.each { |d| @buffer.add(d) }
+        if flush
+          self.flush
+          return
+        end
+        return unless @buffer.pending_count >= FLAG_BATCH_FLUSH_SIZE
+
+        Thread.new { threshold_flush }
+      end
+
+      # POST pending declarations to the flags bulk endpoint.
       #
-      # Idempotent — safe to call multiple times. Called automatically on
-      # first +flag.get+ evaluation if not invoked manually.
+      # Items remain in the buffer until the request succeeds, so a flush
+      # against an unhealthy +flags+ service is automatically retried by the
+      # next +flush+ call (periodic background flush, install retry, or final
+      # flush on close).
       #
-      # If the flags-service is unhealthy (e.g. a coordinated rebuild where
-      # the app pod starts before the schema is loaded), the flush or refresh
-      # will fail. Pending declarations stay queued, the client remains
-      # disconnected, and the next call retries after an exponentially
-      # backed-off delay (capped at +MAX_START_RETRY_DELAY+ seconds).
-      # Evaluations during that window fall back to handle defaults.
-      def start
-        return if @connected
-        return if Process.clock_gettime(Process::CLOCK_MONOTONIC) < @next_start_attempt_at
+      # @return [void]
+      def flush
+        batch = @buffer.peek
+        return if batch.empty?
 
-        @environment = @parent._environment
+        body = build_flag_bulk_request(batch)
+        ApiSupport::ErrorMapping.call { @api.bulk_register_flags(body) }
+        @buffer.commit(batch.map { |b| b["id"] })
+      end
 
-        begin
-          @manage.flags.flush
-          refresh
-        rescue StandardError => e
-          schedule_start_retry(e)
-          return
-        end
+      # Synchronous flush — alias of +flush+ for the periodic-flush path.
+      #
+      # @return [void]
+      def flush_sync
+        flush
+      end
 
-        @connected = true
-        @start_retry_delay = INITIAL_START_RETRY_DELAY
-        @next_start_attempt_at = 0.0
+      # Number of pending flag declarations awaiting flush.
+      #
+      # @return [Integer] number of pending flag declarations awaiting flush.
+      def pending_count
+        @buffer.pending_count
+      end
 
-        @ws_manager = @parent._ensure_ws
-        return if @ws_subscribed
+      # ----------------------------------------------------------------
+      # Live surface: typed flag handles
+      # ----------------------------------------------------------------
 
-        @ws_manager.on("flag_changed") { |data| handle_flag_changed(data) }
-        @ws_manager.on("flag_deleted") { |data| handle_flag_deleted(data) }
-        @ws_manager.on("flags_changed") { |data| handle_flags_changed(data) }
-        @ws_subscribed = true
+      # Declare a boolean flag handle for live evaluation. Connects lazily on first use.
+      #
+      # @param id [String] identifier of the flag to evaluate.
+      # @param default [Boolean] value returned by +handle.get+ when the flag is
+      #   unknown or no environment override or rule applies.
+      # @return [BooleanFlag] a handle whose +get+ evaluates against the live cache.
+      def boolean_flag(id, default:)
+        ensure_connected
+        handle = BooleanFlag.new(self, id: id, name: id, type: "BOOLEAN", default: default)
+        @handles[id] = handle
+        observe_declaration(id, "BOOLEAN", default)
+        handle
+      end
+
+      # Declare a string flag handle for live evaluation. Connects lazily on first use.
+      #
+      # @param id [String] identifier of the flag to evaluate.
+      # @param default [String] value returned by +handle.get+ when the flag is
+      #   unknown or no environment override or rule applies.
+      # @return [StringFlag] a handle whose +get+ evaluates against the live cache.
+      def string_flag(id, default:)
+        ensure_connected
+        handle = StringFlag.new(self, id: id, name: id, type: "STRING", default: default)
+        @handles[id] = handle
+        observe_declaration(id, "STRING", default)
+        handle
       end
 
+      # Declare a numeric flag handle for live evaluation. Connects lazily on first use.
+      #
+      # @param id [String] identifier of the flag to evaluate.
+      # @param default [Numeric] value returned by +handle.get+ when the flag is
+      #   unknown or no environment override or rule applies.
+      # @return [NumberFlag] a handle whose +get+ evaluates against the live cache.
+      def number_flag(id, default:)
+        ensure_connected
+        handle = NumberFlag.new(self, id: id, name: id, type: "NUMERIC", default: default)
+        @handles[id] = handle
+        observe_declaration(id, "NUMERIC", default)
+        handle
+      end
+
+      # Declare a JSON flag handle for live evaluation. Connects lazily on first use.
+      #
+      # @param id [String] identifier of the flag to evaluate.
+      # @param default [Hash] value returned by +handle.get+ when the flag is
+      #   unknown or no environment override or rule applies.
+      # @return [JsonFlag] a handle whose +get+ evaluates against the live cache.
+      def json_flag(id, default:)
+        ensure_connected
+        handle = JsonFlag.new(self, id: id, name: id, type: "JSON", default: default)
+        @handles[id] = handle
+        observe_declaration(id, "JSON", default)
+        handle
+      end
+
+      # ----------------------------------------------------------------
+      # Live surface: refresh / stats / change listeners
+      # ----------------------------------------------------------------
+
+      # Re-fetch all flag definitions and clear cache.
+      #
+      # Connects lazily on first use — no explicit install step.
+      #
+      # @return [void]
       def refresh
-        fetch_all_flags
-        @cache.clear
-        fire_change_listeners_all("manual")
+        ensure_connected
+        do_refresh("manual")
       end
 
+      # Return evaluation statistics. Connects lazily on first use.
+      #
+      # @return [FlagStats] the evaluation statistics.
       def stats
+        ensure_connected
         FlagStats.new(cache_hits: @cache.cache_hits, cache_misses: @cache.cache_misses)
       end
 
@@ -176,7 +492,15 @@ module Smplkit
       #
       #   client.flags.on_change { |event| ... }            # global
       #   client.flags.on_change("checkout-v2") { |e| ... } # flag-scoped
+      #
+      # Connects lazily on first use — no explicit install step.
+      #
+      # @param flag_id [String, nil] optional flag id scoping the listener to
+      #   that flag; when +nil+ a global listener is registered.
+      # @yield [FlagChangeEvent] the listener block, invoked on each change.
+      # @return [Proc] the registered listener block.
       def on_change(flag_id = nil, &block)
+        ensure_connected
         raise ArgumentError, "on_change requires a block" unless block
 
         if flag_id.nil?
@@ -187,25 +511,59 @@ module Smplkit
         block
       end
 
-      def _close
-        # No durable resources here — kept for symmetry with Python SDK.
+      # Release resources — only those this client owns.
+      #
+      # Tears down the owned WebSocket (standalone install). A wired client
+      # borrows the parent's transport, WebSocket, and contexts client and
+      # closes none of them.
+      #
+      # @return [void]
+      def close
+        if @owns_ws && @ws_manager
+          @ws_manager.stop
+          @ws_manager = nil
+          @owns_ws = false
+        end
+        # Owned flags/app transports (standalone construction) release their
+        # Faraday connections on GC; there is no explicit shutdown to call.
+        nil
       end
+      alias _close close
 
-      def _evaluate_handle(flag_id, default, context)
-        start unless @connected
+      # Construct, yield to the block, and close on exit.
+      #
+      # @yield [FlagsClient] the constructed client.
+      # @return [Object] the block's return value; closes the client on exit.
+      def self.open(**kwargs)
+        client = new(**kwargs)
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      end
 
-        eval_dict =
-          if context
-            @manage.contexts.register(context) if @manage.respond_to?(:contexts)
-            contexts_to_eval_dict(context)
-          else
-            current = Smplkit.request_context
-            current.empty? ? {} : contexts_to_eval_dict(current)
-          end
+      # Core evaluation used by flag handles (the +.get+ path).
+      #
+      # Connects lazily on first use so +flag.get+ works without an explicit
+      # install step.
+      def _evaluate_handle(flag_id, default, context)
+        ensure_connected
+        if context
+          # Explicit context: register here. (Implicit set_context registers at
+          # the entry point, so the request-context branch below doesn't need
+          # to.)
+          @contexts&.register(context)
+          eval_dict = Flags.contexts_to_eval_dict(context)
+        else
+          contexts = Smplkit.request_context
+          eval_dict = contexts.empty? ? {} : Flags.contexts_to_eval_dict(contexts)
+        end
 
+        # Auto-inject service context if set and not already provided.
         eval_dict["service"] = { "key" => @service } if @service && !eval_dict.key?("service")
 
-        ctx_hash = hash_context(eval_dict)
+        ctx_hash = Flags.hash_context(eval_dict)
         cache_key = "#{flag_id}:#{ctx_hash}"
 
         hit, cached_value = @cache.get(cache_key)
@@ -229,62 +587,131 @@ module Smplkit
         value
       end
 
+      # Internal: trigger lazy connect. Used by +Client#wait_until_ready+.
+      def _ensure_connected
+        ensure_connected
+      end
+
       private
 
-      def register_handle(klass, id, type_name, default)
-        handle = klass.new(self, id: id, name: id, type: type_name, default: default)
-        @handles[id] = handle
-        if @manage.respond_to?(:flags)
-          @manage.flags.register(FlagDeclaration.new(
-                                   id: id, type: type_name, default: default,
-                                   service: @service, environment: @environment
-                                 ))
+      # Queue a declared flag with the owned discovery buffer.
+      def observe_declaration(flag_id, flag_type, default)
+        register(FlagDeclaration.new(
+                   id: flag_id, type: flag_type, default: default,
+                   service: @service, environment: @environment
+                 ))
+      end
+
+      def threshold_flush
+        flush
+      rescue StandardError => e
+        Smplkit.debug("registration", "flag registration flush failed: #{e.class}: #{e.message}")
+      end
+
+      def model_from_resource(resource)
+        d = Helpers.flag_dict_from_json(resource)
+        klass =
+          case d["type"]
+          when "BOOLEAN" then BooleanFlag
+          when "STRING" then StringFlag
+          when "NUMERIC" then NumberFlag
+          else JsonFlag
+          end
+        klass.new(
+          self,
+          id: d["id"], name: d["name"], type: d["type"], default: d["default"],
+          description: d["description"], values: d["values"], environments: d["environments"],
+          created_at: (resource["attributes"] || {})["created_at"],
+          updated_at: (resource["attributes"] || {})["updated_at"]
+        )
+      end
+
+      # ----------------------------------------------------------------
+      # Live surface: lazy connect + transport / WebSocket helpers
+      # ----------------------------------------------------------------
+
+      def ensure_ws
+        return @parent._ensure_ws unless @parent.nil?
+
+        if @ws_manager.nil?
+          @ws_manager = SharedWebSocket.new(
+            app_base_url: @app_base_url, api_key: @standalone_api_key, metrics: @metrics
+          )
+          @ws_manager.start
+          @owns_ws = true
         end
-        handle
+        @ws_manager
+      end
+
+      # Open the live connection to the running Smpl Flags service.
+      #
+      # Flushes any buffered discovery declarations, fetches all flag
+      # definitions into the local cache, opens the shared WebSocket, and
+      # subscribes to +flag_changed+ / +flag_deleted+ / +flags_changed+ events.
+      #
+      # Idempotent and internal — every live method calls it on first use, so
+      # the live surface auto-connects with no explicit step.
+      def ensure_connected
+        @parent&._ensure_started
+        return if @connected
+
+        # Flush discovered flags BEFORE fetching definitions so the fetch
+        # reflects them. Items stay in the buffer until the POST succeeds.
+        begin
+          flush
+        rescue StandardError => e
+          Smplkit.debug("flags", "discovery flush before connect failed: #{e.class}: #{e.message}")
+        end
+
+        fetch_all_flags
+        @cache.clear
+        @connected = true
+
+        @ws_manager = ensure_ws
+        return if @ws_subscribed
+
+        @ws_manager.on("flag_changed") { |data| handle_flag_changed(data) }
+        @ws_manager.on("flag_deleted") { |data| handle_flag_deleted(data) }
+        @ws_manager.on("flags_changed") { |data| handle_flags_changed(data) }
+        @ws_subscribed = true
       end
 
-      def schedule_start_retry(exc)
-        delay = @start_retry_delay
-        @next_start_attempt_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + delay
-        @start_retry_delay = [delay * 2, MAX_START_RETRY_DELAY].min
-        Smplkit.debug("registration",
-                      "flags client start failed (will retry in #{delay}s): #{exc.class}: #{exc.message}")
+      def do_refresh(_source)
+        fetch_all_flags
+        @cache.clear
+        fire_change_listeners_all("manual")
       end
 
+      # ----------------------------------------------------------------
+      # Internal: flag store
+      # ----------------------------------------------------------------
+
       def fetch_all_flags
-        flags = @parent._flags_transport.list_flags
+        flags = fetch_flags_list
         @flag_store = flags.to_h { |f| [f["id"], f] }
-      rescue Smplkit::Error
-        raise
-      rescue StandardError => e
-        raise Smplkit::ConnectionError, "Failed to fetch flags: #{e.message}"
       end
 
-      def contexts_to_eval_dict(contexts)
-        contexts.to_h { |ctx| [ctx.type, ctx.to_eval_hash] }
+      def fetch_flags_list
+        rows = ApiSupport::PaginatedFetch.collect { |opts| @api.list_flags(opts) }
+        rows.map { |r| Helpers.flag_dict_from_json(ApiSupport::ResourceShim.from_model(r)) }
       end
 
-      def hash_context(eval_dict)
-        Digest::MD5.hexdigest(JSON.generate(deep_sort(eval_dict)))
+      # Fetch a single flag by key and return a store-format dict.
+      def fetch_flag_single_data(key)
+        response = ApiSupport::ErrorMapping.call { @api.get_flag(key) }
+        Helpers.flag_dict_from_json(ApiSupport::ResourceShim.from_model(response.data))
       end
 
-      def deep_sort(value)
-        case value
-        when Hash
-          value.keys.sort_by(&:to_s).to_h { |k| [k, deep_sort(value[k])] }
-        when Array
-          value.map { |v| deep_sort(v) }
-        else
-          value
-        end
-      end
+      # ----------------------------------------------------------------
+      # Internal: event handlers (called by SharedWebSocket)
+      # ----------------------------------------------------------------
 
       def handle_flag_changed(data)
         key = data["id"]
         return unless key
 
         pre = @flag_store[key]&.dup || {}
-        new_data = @parent._flags_transport.fetch_flag(key)
+        new_data = fetch_flag_single_data(key)
         @flag_store[key] = new_data
         @cache.clear
         fire_change_listeners(key, "websocket") if pre != new_data
@@ -314,6 +741,7 @@ module Smplkit
         changed = all_keys.reject { |k| pre_store[k] == post_store[k] }
         return if changed.empty?
 
+        # Global listener fires once.
         first_event = FlagChangeEvent.new(id: changed.first, source: "websocket")
         @global_listeners.each do |cb|
           cb.call(first_event)
@@ -321,6 +749,7 @@ module Smplkit
           Smplkit.debug("flags", "global listener raised: #{e.class}: #{e.message}")
         end
 
+        # Per-key listeners fire for each changed key.
         changed.each do |k|
           deleted = pre_store.key?(k) && !post_store.key?(k)
           event = FlagChangeEvent.new(id: k, source: "websocket", deleted: deleted)
@@ -349,9 +778,9 @@ module Smplkit
 
       # Evaluate a flag definition against the given context.
       #
-      # Follows ADR-022 §2.6 semantics:
-      #   1. Look up the environment. If missing, return flag-level default.
-      #   2. If disabled, return env default or flag default.
+      # Evaluation steps:
+      #   1. Look up the environment. If missing, return the flag-level default.
+      #   2. If disabled, return the env default or flag default.
       #   3. Iterate rules; first match wins.
       #   4. No match -> env default or flag default.
       def evaluate_flag(flag_def, environment, eval_dict)
@@ -378,15 +807,70 @@ module Smplkit
 
         fallback
       end
+
+      def flag_body(flag)
+        SmplkitGeneratedClient::Flags::FlagResponse.new(
+          data: SmplkitGeneratedClient::Flags::FlagResource.new(
+            type: "flag",
+            id: flag.id,
+            attributes: SmplkitGeneratedClient::Flags::Flag.new(
+              name: flag.name,
+              type: flag.type,
+              default: flag.default,
+              description: flag.description,
+              values: flag_values_to_wire(flag.values),
+              environments: flag_envs_to_wire(flag.environments)
+            )
+          )
+        )
+      end
+
+      def flag_values_to_wire(values)
+        # The server requires +values+ to be null (unconstrained) or a
+        # non-empty array (constrained) — an empty array is rejected, so an
+        # empty/cleared values list is sent as null.
+        return nil if values.nil? || values.empty?
+
+        values.map do |v|
+          SmplkitGeneratedClient::Flags::FlagValue.new(name: v.name, value: v.value)
+        end
+      end
+
+      def flag_envs_to_wire(environments)
+        return nil if environments.empty?
+
+        environments.each_with_object({}) do |(env_key, env_obj), out|
+          rules = env_obj.rules.map do |r|
+            SmplkitGeneratedClient::Flags::FlagRule.new(
+              logic: r.logic, value: r.value, description: r.description
+            )
+          end
+          out[env_key] = SmplkitGeneratedClient::Flags::FlagEnvironment.new(
+            enabled: env_obj.enabled, default: env_obj.default, rules: rules
+          )
+        end
+      end
+
+      def build_flag_bulk_request(batch)
+        flag_items = batch.map do |entry|
+          SmplkitGeneratedClient::Flags::FlagBulkItem.new(
+            id: entry["id"], type: entry["type"], default: entry["default"],
+            service: entry["service"], environment: entry["environment"]
+          )
+        end
+        SmplkitGeneratedClient::Flags::FlagBulkRequest.new(flags: flag_items)
+      end
     end
 
     # Vendored minimal JSON Logic evaluator covering the operators the smplkit
     # platform ships in flag rules.
     #
-    # Stays in-tree so the Ruby SDK doesn't depend on the +json_logic+ gem
-    # being correct — the Java SDK followed the same pattern. Operators
-    # supported: +==+, +!=+, +<+, +<=+, +>+, +>=+, +in+, +var+, +and+, +or+,
-    # +!+, +if+, +missing+, +none+.
+    # Stays in-tree so the Ruby SDK doesn't depend on the +json_logic+ gem being
+    # correct — the Java SDK followed the same pattern. Operators supported:
+    # +==+, +!=+, +<+, +<=+, +>+, +>=+, +in+, +var+, +and+, +or+, +!+, +if+,
+    # +missing+, +none+.
+    #
+    # @api private
     module JsonLogicEvaluator
       module_function
 
@@ -505,4 +989,6 @@ module Smplkit
       end
     end
   end
+
+  FlagsClient = Flags::FlagsClient
 end