smplkit 3.0.96 → 3.0.97

data/lib/smplkit/config/models.rb

@@ -16,6 +16,13 @@ module Smplkit
     class ConfigItem
       attr_accessor :name, :value, :type, :description
 
+      # Create a typed config item.
+      #
+      # @param name [String] The item key within its config.
+      # @param value [Object] The item's value.
+      # @param type [String] The item value type — one of +"STRING"+,
+      #   +"NUMBER"+, +"BOOLEAN"+, or +"JSON"+.
+      # @param description [String, nil] Optional human-readable description.
       def initialize(name:, value:, type:, description: nil)
         @name = name
         @value = value
@@ -23,6 +30,8 @@ module Smplkit
         @description = description
       end
 
+      # @return [Hash{String => Object}] The item as a plain Hash, omitting a
+      #   +nil+ description.
       def to_h
         { "name" => @name, "value" => @value, "type" => @type, "description" => @description }.compact
       end
@@ -42,10 +51,13 @@ module Smplkit
     # setters with +environment:+ (e.g.
     # +cfg.set_string("k", "v", environment: "production")+).
     #
-    # Per ADR-024 §2.4 the wire shape for env overrides is flat —
-    # +{env: {key: rawValue}}+ — so the in-memory representation is
-    # simply a Hash of raw values, with no typed wrapper.
+    # An override stores only the raw value; the declared type and description
+    # come from the base item, so an item's type and description are ignored
+    # when an environment override is supplied.
     class ConfigEnvironment
+      # @param values [Hash{String => Object}, nil] Initial overrides as a flat
+      #   +{key => raw_value}+ map. A legacy +{key => {"value" => raw}}+ wrapper
+      #   is unwrapped to the raw value.
       def initialize(values: nil)
         @values_raw = {}
         return unless values
@@ -58,6 +70,9 @@ module Smplkit
       end
 
       # Returns overrides as a plain Hash +{ "key" => raw_value }+.
+      #
+      # @return [Hash{String => Object}] A read-only shallow copy of the
+      #   overrides.
       def values
         @values_raw.dup
       end
@@ -65,6 +80,9 @@ module Smplkit
       # Returns overrides as a plain Hash +{ "key" => raw_value }+. Retained
       # as a separate accessor for backward compatibility; identical to
       # +values+ now that env overrides are stored flat.
+      #
+      # @return [Hash{String => Object}] A read-only shallow copy of the
+      #   overrides.
       def values_raw
         @values_raw.dup
       end
@@ -82,6 +100,20 @@ module Smplkit
     class Config
       attr_accessor :id, :key, :name, :description, :parent_id, :created_at, :updated_at
 
+      # @param client [ConfigClient, nil] The owning client, or +nil+ for a
+      #   detached model that cannot save or delete.
+      # @param key [String] The config identifier (slug).
+      # @param id [String, nil] The server-assigned id, or +nil+ for an unsaved
+      #   config.
+      # @param name [String, nil] Display name.
+      # @param description [String, nil] Optional description.
+      # @param parent_id [String, nil] Parent config id (slug), or +nil+ for a
+      #   root config.
+      # @param items [Array<ConfigItem>, nil] Base items.
+      # @param environments [Hash{String => ConfigEnvironment}, nil]
+      #   Per-environment overrides keyed by environment id.
+      # @param created_at [Object, nil] Creation timestamp.
+      # @param updated_at [Object, nil] Last-modified timestamp.
       def initialize(client = nil, key:, id: nil, name: nil, description: nil,
                      parent_id: nil, items: nil, environments: nil,
                      created_at: nil, updated_at: nil)
@@ -97,14 +129,25 @@ module Smplkit
         @updated_at = updated_at
       end
 
+      # @return [Array<ConfigItem>] A read-only shallow copy of the base items.
       def items
         @items.dup
       end
 
+      # @return [Hash{String => ConfigEnvironment}] A read-only shallow copy of
+      #   the per-environment overrides keyed by environment id.
       def environments
         @environments.dup
       end
 
+      # Persist this config to the server. Creates a new config if unsaved, or
+      # updates the existing one.
+      #
+      # @return [self]
+      # @raise [Smplkit::NotFoundError] If the config no longer exists
+      #   (update).
+      # @raise [Smplkit::ValidationError] If the server rejects the request.
+      # @raise [RuntimeError] If the model was constructed without a client.
       def save
         raise "Config was constructed without a client; cannot save" if @client.nil?
 
@@ -119,6 +162,10 @@ module Smplkit
       end
       alias save! save
 
+      # Delete this config from the server.
+      #
+      # @return [void]
+      # @raise [RuntimeError] If the model was constructed without a client.
       def delete
         raise "Config was constructed without a client; cannot delete" if @client.nil?
 
@@ -126,26 +173,86 @@ module Smplkit
       end
       alias delete! delete
 
+      # Set (or replace) an item. When +environment:+ is given, sets an
+      # override on that environment.
+      #
+      # An environment override stores only the raw value; the declared type and
+      # description come from the base item, so the +ConfigItem+'s type and
+      # description are ignored when +environment:+ is supplied.
+      #
+      # @param item [ConfigItem] The item to set; its +name+ is the item key.
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @return [self]
+      def set(item, environment: nil)
+        set_typed(item.name, item.value, item.type, environment: environment, description: item.description)
+      end
+
+      # Convenience: set a STRING item (or environment override).
+      #
+      # @param name [String] The item key to set.
+      # @param value [String] The string value.
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @param description [String, nil] Optional human-readable description.
+      #   Ignored when setting an environment override.
+      # @return [self]
       def set_string(name, value, environment: nil, description: nil)
         set_typed(name, value, ItemType::STRING, environment: environment, description: description)
       end
 
+      # Convenience: set a NUMBER item (or environment override).
+      #
+      # @param name [String] The item key to set.
+      # @param value [Integer, Float] The numeric value.
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @param description [String, nil] Optional human-readable description.
+      #   Ignored when setting an environment override.
+      # @return [self]
       def set_number(name, value, environment: nil, description: nil)
         set_typed(name, value, ItemType::NUMBER, environment: environment, description: description)
       end
 
+      # Convenience: set a BOOLEAN item (or environment override).
+      #
+      # @param name [String] The item key to set.
+      # @param value [Boolean] The boolean value.
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @param description [String, nil] Optional human-readable description.
+      #   Ignored when setting an environment override.
+      # @return [self]
       def set_boolean(name, value, environment: nil, description: nil)
         set_typed(name, value, ItemType::BOOLEAN, environment: environment, description: description)
       end
 
+      # Convenience: set a JSON item (or environment override).
+      #
+      # @param name [String] The item key to set.
+      # @param value [Object] Any JSON-serializable value (Hash, Array, or
+      #   primitive).
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @param description [String, nil] Optional human-readable description.
+      #   Ignored when setting an environment override.
+      # @return [self]
       def set_json(name, value, environment: nil, description: nil)
         set_typed(name, value, ItemType::JSON, environment: environment, description: description)
       end
 
-      def remove_item(name, environment: nil)
+      # Remove an item by name. When +environment:+ is given, removes the
+      # per-environment override only. Removing an item that isn't present is a
+      # no-op.
+      #
+      # @param name [String] The item key to remove.
+      # @param environment [String, nil] When given, remove only this
+      #   environment's override for +name+, leaving the base item intact.
+      # @return [self]
+      def remove(name, environment: nil)
         if environment
           env = @environments[environment]
-          return unless env
+          return self unless env
 
           raw = env.values_raw
           raw.delete(name)
@@ -181,8 +288,8 @@ module Smplkit
             @items << ConfigItem.new(name: name, value: value, type: type, description: description)
           end
         else
-          # Per ADR-024 §2.4 env overrides carry the raw value only — type
-          # and description live on the base item, not on the override.
+          # Env overrides carry the raw value only — type and description live
+          # on the base item, not on the override.
           env = (@environments[environment] ||= ConfigEnvironment.new)
           raw = env.values_raw
           raw[name] = value

data/lib/smplkit/config_resolution.rb

@@ -4,6 +4,8 @@ require_relative "errors"
 
 module Smplkit
   # SDK configuration resolution: defaults -> file -> env vars -> constructor args.
+  #
+  # @api private
   module ConfigResolution
     CONFIG_KEYS = {
       "api_key" => "SMPLKIT_API_KEY",
@@ -33,7 +35,7 @@ module Smplkit
       keyword_init: true
     )
 
-    ResolvedManagementConfig = Struct.new(
+    ResolvedClientConfig = Struct.new(
       :api_key, :base_domain, :scheme, :debug, :extra_headers,
       keyword_init: true
     )
@@ -157,8 +159,8 @@ module Smplkit
       )
     end
 
-    def resolve_management_config(profile: nil, api_key: nil, base_domain: nil,
-                                  scheme: nil, debug: nil, home_dir: nil)
+    def resolve_client_config(profile: nil, api_key: nil, base_domain: nil,
+                              scheme: nil, debug: nil, home_dir: nil)
       resolved = {
         "api_key" => nil,
         "base_domain" => "smplkit.com",
@@ -191,7 +193,7 @@ module Smplkit
 
       missing_required(resolved, "api_key", active_profile)
 
-      ResolvedManagementConfig.new(
+      ResolvedClientConfig.new(
         api_key: resolved["api_key"].to_s,
         base_domain: resolved["base_domain"].to_s,
         scheme: resolved["scheme"].to_s,

data/lib/smplkit/errors.rb

@@ -6,9 +6,9 @@ module Smplkit
   # A single error object from the server's JSON:API +errors+ array.
   #
   # +code+ is the application-specific machine-readable error code (e.g.
-  # +environment_unmanaged+); per JSON:API §7 and ADR-014, smplkit sets
-  # this on every error so callers can branch without string-matching
-  # the human +detail+. +meta+ carries additional structured context
+  # +environment_unmanaged+); smplkit sets this on every error so callers
+  # can branch without string-matching the human +detail+. +meta+ carries
+  # additional structured context
   # (e.g. <tt>{"environment" => "staging"}</tt>).
   class ApiErrorDetail
     attr_reader :status, :code, :title, :detail, :source, :meta
@@ -62,6 +62,7 @@ module Smplkit
       end
     end
 
+    # @api private — Build a human-readable message from a list of error details.
     def self.derive_message(errors)
       return "An API error occurred" if errors.nil? || errors.empty?
 
@@ -92,6 +93,8 @@ module Smplkit
   # this.
   class NotInstalledError < Error; end
 
+  # @api private — Internal helpers that parse JSON:API error bodies and map
+  #   HTTP status codes onto the error classes above.
   module Errors
     module_function
 

data/lib/smplkit/flags/client.rb

@@ -8,7 +8,7 @@ require "digest"
 # Smpl Flags has two surfaces on a single client, mirroring how the config,
 # audit, and jobs clients expose their full surface from one class:
 #
-# * *Management surface* — pure CRUD, no live connection: +new_boolean_flag+ /
+# * *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
@@ -33,6 +33,14 @@ require "digest"
 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
 
@@ -54,6 +62,8 @@ module Smplkit
     end
 
     # Thread-safe LRU resolution cache with hit/miss stats.
+    #
+    # @api private
     class ResolutionCache
       DEFAULT_MAX_SIZE = 10_000
 
@@ -96,18 +106,29 @@ 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)
 
     # Convert a list of Context objects to the nested evaluation dict.
+    #
+    # @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
@@ -127,15 +148,17 @@ module Smplkit
     # 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_management_config(
+      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::ResolvedManagementConfig.new(
+      tcfg = ConfigResolution::ResolvedClientConfig.new(
         api_key: resolved_key, base_domain: cfg.base_domain, scheme: cfg.scheme,
         debug: cfg.debug, extra_headers: merged
       )
@@ -156,7 +179,7 @@ module Smplkit
     #   beta = flags.boolean_flag("beta", default: false)
     #   beta.get # => ...
     #
-    # The management surface (+new_*+ / +get+ / +list+ / +delete+ and discovery)
+    # 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
@@ -208,6 +231,14 @@ module Smplkit
       # ----------------------------------------------------------------
 
       # 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),
@@ -218,6 +249,17 @@ module Smplkit
       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),
@@ -226,6 +268,17 @@ module Smplkit
       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),
@@ -234,6 +287,17 @@ module Smplkit
       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),
@@ -242,12 +306,22 @@ module Smplkit
       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
 
       # 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?
@@ -257,6 +331,10 @@ module Smplkit
       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
@@ -277,6 +355,14 @@ module Smplkit
       # ----------------------------------------------------------------
 
       # Buffer flag declarations for bulk-discovery upload; optionally flush now.
+      #
+      # @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) }
@@ -295,6 +381,8 @@ module Smplkit
       # against an unhealthy +flags+ service is automatically retried by the
       # next +flush+ call (periodic background flush, install retry, or final
       # flush on close).
+      #
+      # @return [void]
       def flush
         batch = @buffer.peek
         return if batch.empty?
@@ -305,11 +393,15 @@ module Smplkit
       end
 
       # Synchronous flush — alias of +flush+ for the periodic-flush path.
+      #
+      # @return [void]
       def flush_sync
         flush
       end
 
       # Number of pending flag declarations awaiting flush.
+      #
+      # @return [Integer] number of pending flag declarations awaiting flush.
       def pending_count
         @buffer.pending_count
       end
@@ -319,6 +411,11 @@ module Smplkit
       # ----------------------------------------------------------------
 
       # 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)
@@ -328,6 +425,11 @@ module Smplkit
       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)
@@ -337,6 +439,11 @@ module Smplkit
       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)
@@ -346,6 +453,11 @@ module Smplkit
       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)
@@ -361,12 +473,16 @@ module Smplkit
       # Re-fetch all flag definitions and clear cache.
       #
       # Connects lazily on first use — no explicit install step.
+      #
+      # @return [void]
       def refresh
         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)
@@ -378,6 +494,11 @@ module Smplkit
       #   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
@@ -395,6 +516,8 @@ module Smplkit
       # 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
@@ -408,6 +531,9 @@ module Smplkit
       alias _close close
 
       # 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
@@ -652,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)
@@ -743,6 +869,8 @@ module Smplkit
     # correct — the Java SDK followed the same pattern. Operators supported:
     # +==+, +!=+, +<+, +<=+, +>+, +>=+, +in+, +var+, +and+, +or+, +!+, +if+,
     # +missing+, +none+.
+    #
+    # @api private
     module JsonLogicEvaluator
       module_function