legion-settings 1.3.27 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a096c46e4b074a4e77c104f21b1dc89b953ad15370e514ccd7face8cf8a7b8f
-  data.tar.gz: 06475bdc9bf41c6219e2c61fef17006346bb57b833a9a6c992a02f1d1178047a
+  metadata.gz: baf40211abee6a48e5863077ce8e31fa416afbad9f003933e7edcfca4b8a72ba
+  data.tar.gz: f8faf5fb5eadead569c9f222a70c58e5ac11bc923dc281bd587f3f2704125cd0
 SHA512:
-  metadata.gz: 30cc986020bd6c2f4c783193f65fb07b935e08ddadd1a00608a90001a8312da19e88612e99449bc283ae4d716d119f22517c37809670f50e854a8658502c645f
-  data.tar.gz: 7d41547be02a86b3afc065e8865dbe16c02ebde7b592bd7f9a83585b22d7f07cfc1fe078eb171b754f2398d9fce9942410e8b9b999e744a73ee6abf378ada1bb
+  metadata.gz: 7dbe223a77152d41812ec94bd98457db0570dae8bdea879f58b4ec052fca03eed46d1364617d4affb73d4cd7bc0364e6f6074c5a0fe5d8c433776e900d354417
+  data.tar.gz: b362c5d3a541c5afce645b47656ef1a427b65d58500bd5100e14717451dacaa8024823a188fd97f2475cb2ab1e176912c30ed7ba0496f0f512dd79a593228401

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Legion::Settings Changelog
 
+## [1.4.0] - 2026-04-29
+
+### Added
+- `Legion::Settings::Extensions` — thread-safe runtime registry for extensions, runners, and tools
+- `register_extension`, `register_runner`, `register_tool` — registration methods called during LegionIO boot pipeline
+- `transition(name, state)` — lifecycle state transitions (:discovered, :loaded, :running, :stopped)
+- `extensions`, `runners`, `tools` — query methods returning frozen snapshots of all registered entries
+- `find_extension`, `find_runner`, `find_tool` — lookup by name returning frozen copies
+- `filter_tools(**criteria)` — filter by extension, deferred, sticky, mcp_tier, tags, category, state, source
+- `filter_extensions(**criteria)` — filter by state, category, phase
+- `unregister_extension(name)` — cascade-removes extension and its associated runners and tools
+- `unregister_tool(name)` — remove a single tool
+- `reset!` — clear all registries (for test cleanup)
+- `extension_count`, `runner_count`, `tool_count` — convenience count methods
+- All read operations return frozen duplicates to prevent mutation of registry internals
+- Thread-safe reads and writes via `Concurrent::Map` without explicit locking
+
 ## [1.3.27] - 2026-04-27
 
 ### Added

data/legion-settings.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
     'rubygems_mfa_required' => 'true'
   }
 
+  spec.add_dependency 'concurrent-ruby', '>= 1.2'
   spec.add_dependency 'legion-json', '>= 1.2.0'
   spec.add_dependency 'legion-logging', '>= 1.5.0'
 end

data/lib/legion/settings/deep_merge.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'concurrent/hash'
+
+module Legion
+  module Settings
+    # Shared deep-merge logic used by Loader, Overlay, ProjectEnv, and
+    # the top-level Settings module.  Consolidates four previously
+    # duplicated implementations into one place.
+    module DeepMerge
+      module_function
+
+      # Non-destructive deep merge.  Returns a new hash with +override+
+      # values merged on top of +base+.  Preserves Concurrent::Hash type
+      # when the base hash is one.
+      #
+      # @param base     [Hash] the base hash
+      # @param override [Hash] values to merge on top
+      # @return [Hash]
+      def deep_merge(base, override)
+        merged = base.is_a?(Concurrent::Hash) ? Concurrent::Hash[base] : base.dup
+        override.each do |key, value|
+          existing = base[key]
+          merged[key] = if existing.is_a?(Hash) && value.is_a?(Hash)
+                          deep_merge(existing, value)
+                        elsif existing.is_a?(Array) && value.is_a?(Array)
+                          (existing + value).uniq
+                        else
+                          value
+                        end
+        end
+        merged
+      end
+
+      # In-place deep merge.  Mutates +base+ with values from +override+.
+      # Nested hashes are merged recursively; scalars and arrays are replaced.
+      #
+      # @param base     [Hash] the hash to mutate
+      # @param override [Hash] values to merge in
+      # @return [Hash] the mutated base hash
+      def deep_merge!(base, override)
+        override.each do |key, value|
+          if base[key].is_a?(Hash) && value.is_a?(Hash)
+            deep_merge!(base[key], value)
+          else
+            base[key] = value
+          end
+        end
+        base
+      end
+    end
+  end
+end

data/lib/legion/settings/extensions/filter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Legion
+  module Settings
+    module Extensions
+      # Filter helpers for querying tools and extensions by criteria.
+      module Filter
+        module_function
+
+        # Filter tool entries by criteria.
+        #
+        # Supported criteria:
+        #   - extension: [String, Symbol] filter by extension name
+        #   - deferred: [Boolean] filter by deferred flag
+        #   - sticky: [Boolean] filter by sticky flag
+        #   - mcp_tier: [Integer] filter by MCP tier
+        #   - tags: [Array<String>] match any tag
+        #   - category: [String, Symbol] filter by mcp_category
+        #   - state: [Symbol] filter tools whose extension is in this state
+        #   - source: [Symbol] filter by source (:discovery, :manual, :static)
+        TOOL_EXACT_FILTERS = {
+          deferred: :deferred, sticky: :sticky, mcp_tier: :mcp_tier, source: :source
+        }.freeze
+
+        TOOL_NORMALIZED_FILTERS = {
+          extension: :extension, category: :mcp_category
+        }.freeze
+
+        def apply_tool_filters(entries, criteria, extension_store: nil)
+          result = entries.dup
+          apply_exact_tool_filters!(result, criteria)
+          apply_normalized_tool_filters!(result, criteria)
+          filter_by_tags!(result, criteria[:tags]) if criteria.key?(:tags)
+          filter_by_extension_state!(result, criteria[:state], extension_store) if criteria.key?(:state) && extension_store
+          result
+        end
+
+        def apply_exact_tool_filters!(result, criteria)
+          TOOL_EXACT_FILTERS.each do |criteria_key, entry_key|
+            next unless criteria.key?(criteria_key)
+
+            value = criteria[criteria_key]
+            result.select! { |t| t[entry_key] == value }
+          end
+        end
+
+        def apply_normalized_tool_filters!(result, criteria)
+          TOOL_NORMALIZED_FILTERS.each do |criteria_key, entry_key|
+            next unless criteria.key?(criteria_key)
+
+            value = normalize(criteria[criteria_key])
+            result.select! { |t| normalize(t[entry_key]) == value }
+          end
+        end
+
+        # Filter extension entries by criteria.
+        #
+        # Supported criteria:
+        #   - state: [Symbol] filter by lifecycle state
+        #   - data_required, cache_required, llm_required, etc.: [Boolean] filter by requirement flags
+        #   - category: [String, Symbol] filter by category
+        #   - phase: [Integer] filter by phase
+        EXTENSION_BOOLEAN_FILTERS = %i[
+          data_required cache_required transport_required crypt_required
+          vault_required llm_required skills_required remote_invocable
+          mcp_tools mcp_tools_deferred sticky_tools hot_reloadable
+        ].freeze
+
+        def apply_extension_filters(entries, criteria)
+          result = entries.dup
+          result.select! { |e| e[:state] == criteria[:state] } if criteria.key?(:state)
+          result.select! { |e| normalize(e[:category]) == normalize(criteria[:category]) } if criteria.key?(:category)
+          result.select! { |e| e[:phase] == criteria[:phase] } if criteria.key?(:phase)
+          apply_extension_boolean_filters!(result, criteria)
+          result
+        end
+
+        def apply_extension_boolean_filters!(result, criteria)
+          EXTENSION_BOOLEAN_FILTERS.each do |key|
+            next unless criteria.key?(key)
+
+            result.select! { |e| e[key] == criteria[key] }
+          end
+        end
+
+        def filter_by_tags!(result, tags)
+          tags = Array(tags).map(&:to_s)
+          result.select! { |t| Array(t[:tags]).map(&:to_s).intersect?(tags) }
+        end
+
+        def filter_by_extension_state!(result, state, extension_store)
+          result.select! do |t|
+            ext = extension_store.find(t[:extension])
+            ext && ext[:state] == state
+          end
+        end
+
+        def normalize(value)
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/extensions/normalizer.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Legion
+  module Settings
+    module Extensions
+      # Normalizes tool, runner, and extension entries into complete, known schemas.
+      #
+      # This is the single source of truth for what fields exist on each entry type.
+      # Every field that ANY consumer reads is defined here. Consumers can access
+      # any field without defensive nil-checks — absent values are explicitly nil,
+      # empty arrays, or empty hashes.
+      #
+      # If a new consumer needs a field, add it here — don't rely on passthrough.
+      module Normalizer
+        module_function
+
+        # -------------------------------------------------------------------
+        # Tool: generated from an exposed runner function or hand-authored
+        # -------------------------------------------------------------------
+        #
+        # Consumers:
+        #   legion-llm: ToolDefinition wire format, executor tool loop, dispatcher
+        #   legion-mcp: ToolAdapter, server registration, deferred registry
+        #   legion-rbac: access control by extension/function
+        #   LegionIO API: tool listing, diagnostics
+        def normalize_tool(name, metadata)
+          {
+            # Identity
+            name:          name.to_s,
+            description:   resolve_string(metadata, :description),
+            input_schema:  resolve_schema(metadata),
+
+            # Execution
+            tool_class:    metadata[:tool_class],
+            dispatch_type: resolve_dispatch_type(metadata),
+
+            # Back-references to owning extension/runner/function
+            extension:     resolve_string(metadata, :extension) || resolve_string(metadata, :ext_name),
+            runner:        resolve_string(metadata, :runner) || resolve_string(metadata, :runner_snake),
+            function:      resolve_string(metadata, :function),
+
+            # Classification
+            deferred:      metadata[:deferred] == true,
+            sticky:        metadata.fetch(:sticky, true) == true,
+            mcp_tier:      metadata[:mcp_tier],
+            mcp_category:  resolve_string(metadata, :mcp_category),
+            trigger_words: Array(metadata[:trigger_words]).map(&:to_s),
+            tags:          Array(metadata[:tags]).map(&:to_s),
+            source:        metadata.fetch(:source, :unknown).to_sym,
+
+            # Confidence / override tracking (written by Tools::Confidence)
+            confidence:    metadata[:confidence],
+            hit_count:     metadata[:hit_count],
+            miss_count:    metadata[:miss_count]
+          }
+        end
+
+        # -------------------------------------------------------------------
+        # Runner: a module on an extension that exposes callable functions
+        # -------------------------------------------------------------------
+        #
+        # Consumers:
+        #   LegionIO Tools::Discovery: function synthesis, schema building
+        #   legion-mcp runner_catalog: runner listing
+        #   legion-mcp FunctionDiscovery: tool building from runner methods
+        def normalize_runner(name, metadata)
+          {
+            # Identity
+            name:          name.to_s,
+            extension:     resolve_string(metadata, :extension),
+            runner_module: resolve_string(metadata, :runner_module),
+
+            # Functions exposed by this runner
+            function:      resolve_string(metadata, :function),
+            functions:     metadata[:functions] || metadata[:class_methods] || {},
+            exposed:       metadata.fetch(:exposed, true) == true,
+            definition:    metadata[:definition],
+
+            # MCP/tool behavior inherited by functions on this runner
+            mcp_tools:     metadata[:mcp_tools],
+            mcp_deferred:  metadata[:mcp_deferred],
+            trigger_words: Array(metadata[:trigger_words]).map(&:to_s)
+          }
+        end
+
+        # -------------------------------------------------------------------
+        # Extension: a loaded LEX gem with runners, actors, and tools
+        # -------------------------------------------------------------------
+        #
+        # Consumers:
+        #   LegionIO boot pipeline: phased loading, lifecycle management
+        #   LegionIO HandleRegistry: state tracking, hot reload
+        #   LegionIO Registry::Governance: approval, risk tier, naming
+        #   LegionIO Registry::SecurityScanner: checksum, static analysis
+        #   LegionIO Catalog::Available: static listing
+        #   LegionIO API: extension listing, diagnostics
+        #   legion-mcp: extension_info resource
+        #   legion-llm: extension filter in tool queries
+        def normalize_extension(name, metadata) # rubocop:disable Metrics/AbcSize
+          segments = resolve_segments(name, metadata)
+          {
+            # Identity (derived from gem name via Helpers::Segments conventions)
+            name:                     name.to_s,
+            gem_name:                 resolve_string(metadata, :gem_name) || name.to_s,
+            description:              resolve_string(metadata, :description),
+            version:                  resolve_string(metadata, :version),
+            const_path:               resolve_string(metadata, :const_path),
+            segments:                 segments,
+            lex_name:                 resolve_string(metadata, :lex_name) || segments.join('_'),
+            lex_slug:                 resolve_string(metadata, :lex_slug) || segments.join('.'),
+            amqp_prefix:              resolve_string(metadata, :amqp_prefix),
+            settings_path:            resolve_string(metadata, :settings_path),
+            table_prefix:             resolve_string(metadata, :table_prefix),
+
+            # Lifecycle state
+            state:                    metadata.fetch(:state, :discovered).to_sym,
+            loaded_at:                metadata[:loaded_at],
+            last_error:               metadata[:last_error],
+
+            # Boot classification
+            category:                 metadata[:category],
+            tier:                     metadata[:tier],
+            phase:                    metadata[:phase],
+
+            # Requirement flags — queryable WITHOUT loading the extension module.
+            # LegionIO boot checks these to skip extensions whose deps aren't ready.
+            # Defaults match Core module defaults so unset flags behave identically.
+            data_required:            metadata.fetch(:data_required, false) == true,
+            cache_required:           metadata.fetch(:cache_required, false) == true,
+            transport_required:       metadata.fetch(:transport_required, true) == true,
+            crypt_required:           metadata.fetch(:crypt_required, false) == true,
+            vault_required:           metadata.fetch(:vault_required, false) == true,
+            llm_required:             metadata.fetch(:llm_required, false) == true,
+            skills_required:          metadata.fetch(:skills_required, false) == true,
+            remote_invocable:         metadata.fetch(:remote_invocable, true) == true,
+
+            # Extension contents
+            runners:                  Array(metadata[:runners]),
+            actors:                   Array(metadata[:actors]),
+            tools:                    Array(metadata[:tools]),
+            absorbers:                Array(metadata[:absorbers]),
+            routes:                   Array(metadata[:routes]),
+
+            # Gem metadata
+            spec:                     metadata[:spec],
+            gem_dir:                  resolve_string(metadata, :gem_dir),
+            active_version:           resolve_string(metadata, :active_version),
+            latest_installed_version: resolve_string(metadata, :latest_installed_version),
+            loaded_features:          Array(metadata[:loaded_features]),
+
+            # Reload support
+            reload_state:             metadata.fetch(:reload_state, :idle),
+            hot_reloadable:           metadata[:hot_reloadable] == true,
+
+            # Governance / security
+            author:                   resolve_string(metadata, :author),
+            risk_tier:                resolve_string(metadata, :risk_tier),
+            airb_status:              resolve_string(metadata, :airb_status),
+            permissions:              Array(metadata[:permissions]),
+            checksum:                 resolve_string(metadata, :checksum),
+
+            # Tool behavior defaults
+            mcp_tools:                metadata.fetch(:mcp_tools, true) == true,
+            mcp_tools_deferred:       metadata.fetch(:mcp_tools_deferred, true) == true,
+            sticky_tools:             metadata.fetch(:sticky_tools, true) == true,
+
+            # Extension settings — the complete declared configuration with
+            # effective runtime values (defaults merged with user overrides).
+            # Enables introspection: "what can I configure?" and "what's the
+            # current value?" without loading the extension module.
+            # Populated by LegionIO from default_settings merged with
+            # Legion::Settings[:extensions][:lex_name] at registration time.
+            settings_schema:          metadata[:settings_schema] || {},
+            settings:                 metadata[:settings] || {}
+          }
+        end
+
+        # -------------------------------------------------------------------
+        # Schema resolution
+        # -------------------------------------------------------------------
+
+        def resolve_schema(metadata)
+          schema = metadata[:input_schema] || metadata[:parameters] || metadata[:params_schema]
+          schema.is_a?(Hash) ? schema : {}
+        end
+
+        # -------------------------------------------------------------------
+        # Dispatch type detection
+        # -------------------------------------------------------------------
+
+        def resolve_dispatch_type(metadata)
+          return metadata[:dispatch_type].to_sym if metadata[:dispatch_type]
+
+          tool_class = metadata[:tool_class]
+          return :runner if tool_class.nil? && metadata[:extension] && metadata[:function]
+          return :none unless tool_class
+
+          if tool_class.respond_to?(:new) && tool_class.method_defined?(:execute)
+            :instance
+          elsif tool_class.respond_to?(:call)
+            :class_call
+          else
+            :none
+          end
+        end
+
+        def resolve_string(metadata, key)
+          value = metadata[key]
+          value&.to_s
+        end
+
+        # Derive segments from the published gem name. No magic, no lookup tables.
+        #
+        # Rules (matching Ruby gem → module conventions):
+        #   dash '-'       = module boundary:   lex-agentic-learning → ['agentic', 'learning'] → Agentic::Learning
+        #   underscore '_' = CamelCase inside:  lex-microsoft_teams  → ['microsoft_teams']     → MicrosoftTeams
+        #
+        # Examples:
+        #   lex-github              → ['github']                       → Legion::Extensions::Github
+        #   lex-agentic-learning    → ['agentic', 'learning']          → Legion::Extensions::Agentic::Learning
+        #   lex-llm-openai          → ['llm', 'openai']               → Legion::Extensions::Llm::Openai
+        #   lex-llm-azure-foundry   → ['llm', 'azure', 'foundry']     → Legion::Extensions::Llm::Azure::Foundry
+        #   lex-llm-azure_foundry   → ['llm', 'azure_foundry']        → Legion::Extensions::Llm::AzureFoundry
+        #   lex-microsoft_teams     → ['microsoft_teams']              → Legion::Extensions::MicrosoftTeams
+        def resolve_segments(name, metadata)
+          return Array(metadata[:segments]) if metadata[:segments]&.any?
+
+          gem = (metadata[:gem_name] || name).to_s
+          base = gem.start_with?('lex-') ? gem.sub(/\Alex-/, '') : gem
+          base.split('-')
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/extensions/store.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+
+module Legion
+  module Settings
+    module Extensions
+      # Thread-safe registry store backed by Concurrent::Map.
+      #
+      # Each store holds one type of entry (extensions, runners, or tools).
+      # Entries are plain hashes keyed by normalized string name.
+      # Read operations return frozen duplicates so callers cannot mutate internals.
+      class Store
+        def initialize
+          @map = Concurrent::Map.new
+        end
+
+        def register(name, metadata = {})
+          key = normalize_key(name)
+          entry = metadata.merge(name: key, registered_at: Time.now)
+          @map[key] = entry
+          entry.freeze
+        end
+
+        def find(name)
+          @map[normalize_key(name)]&.dup&.freeze
+        end
+
+        def all
+          snapshot = @map.values.map(&:dup)
+          snapshot.each(&:freeze)
+          snapshot.freeze
+        end
+
+        def filter(**_criteria, &block)
+          result = @map.values.map(&:dup)
+          result.select!(&block) if block
+          result.each(&:freeze)
+          result.freeze
+        end
+
+        def delete(name)
+          @map.delete(normalize_key(name))
+        end
+
+        def delete_where(&block)
+          @map.each_pair { |k, v| @map.delete(k) if block.call(v) }
+        end
+
+        def update(name, **extra)
+          key = normalize_key(name)
+          old_entry = @map[key]
+          return nil unless old_entry
+
+          updated = old_entry.dup.merge(extra.merge(updated_at: Time.now))
+          @map[key] = updated
+          updated.freeze
+        end
+
+        def size
+          @map.size
+        end
+
+        def any?
+          @map.size.positive?
+        end
+
+        def clear
+          @map.clear
+        end
+
+        private
+
+        def normalize_key(name)
+          name.to_s
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/extensions.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative 'extensions/store'
+require_relative 'extensions/filter'
+require_relative 'extensions/normalizer'
+
+module Legion
+  module Settings
+    # Thread-safe runtime registry for extensions, runners, and tools.
+    #
+    # Used by the LegionIO boot pipeline to register discovered extensions,
+    # their runner modules, and individual tools. Consumers (legion-mcp,
+    # legion-llm, legion-rbac, API) read from this registry at runtime.
+    #
+    # Each store is a Concurrent::Map-backed Store instance. Read operations
+    # return frozen duplicates so callers cannot mutate registry internals.
+    module Extensions
+      @extension_store = Store.new
+      @runner_store = Store.new
+      @tool_store = Store.new
+
+      class << self
+        # ----------------------------------------------------------------
+        # Registration (called during LegionIO boot pipeline)
+        # ----------------------------------------------------------------
+
+        def register_extension(name, metadata = {})
+          normalized = Normalizer.normalize_extension(name, metadata)
+          @extension_store.register(name, normalized)
+        end
+
+        def register_runner(name, metadata = {})
+          normalized = Normalizer.normalize_runner(name, metadata)
+          @runner_store.register(name, normalized)
+        end
+
+        def register_tool(name, metadata = {})
+          normalized = Normalizer.normalize_tool(name, metadata)
+          @tool_store.register(name, normalized)
+        end
+
+        def transition(name, state, **extra)
+          @extension_store.update(name, state: state, transitioned_at: Time.now, **extra)
+        end
+
+        # ----------------------------------------------------------------
+        # Query (called by legion-mcp, legion-llm, legion-rbac, API)
+        # ----------------------------------------------------------------
+
+        def extensions
+          @extension_store.all
+        end
+
+        def runners
+          @runner_store.all
+        end
+
+        def tools
+          @tool_store.all
+        end
+
+        def find_extension(name)
+          @extension_store.find(name)
+        end
+
+        def find_runner(name)
+          @runner_store.find(name)
+        end
+
+        def find_tool(name)
+          @tool_store.find(name)
+        end
+
+        def filter_tools(**criteria)
+          entries = @tool_store.all.map(&:dup)
+          result = Filter.apply_tool_filters(entries, criteria, extension_store: @extension_store)
+          result.each(&:freeze)
+          result.freeze
+        end
+
+        def filter_extensions(**criteria)
+          entries = @extension_store.all.map(&:dup)
+          result = Filter.apply_extension_filters(entries, criteria)
+          result.each(&:freeze)
+          result.freeze
+        end
+
+        # ----------------------------------------------------------------
+        # Lifecycle
+        # ----------------------------------------------------------------
+
+        def unregister_extension(name)
+          removed = @extension_store.delete(name)
+          return nil unless removed
+
+          key = name.to_s
+          @runner_store.delete_where { |v| v[:extension].to_s == key }
+          @tool_store.delete_where { |v| v[:extension].to_s == key }
+          removed
+        end
+
+        def unregister_tool(name)
+          @tool_store.delete(name)
+        end
+
+        def reset!
+          @extension_store.clear
+          @runner_store.clear
+          @tool_store.clear
+        end
+
+        # ----------------------------------------------------------------
+        # Counts
+        # ----------------------------------------------------------------
+
+        def extension_count
+          @extension_store.size
+        end
+
+        def runner_count
+          @runner_store.size
+        end
+
+        def tool_count
+          @tool_store.size
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/helper.rb

@@ -1,41 +1,119 @@
 # frozen_string_literal: true
 
+require 'concurrent/hash'
+
 module Legion
   module Settings
     module Helper
+      # Namespace boundary words — segment extraction stops at these.
+      # Matches LegionIO's Extensions::Helpers::Base::NAMESPACE_BOUNDARIES.
+      NAMESPACE_BOUNDARIES = %w[Actor Actors Runners Helpers Transport Data].freeze
+
+      # Returns the gem-level settings hash for this extension.
+      # Sub-modules (ConceptualBlending inside Agentic::Language) get
+      # the SAME hash as the root — they access their section via key:
+      #   settings[:conceptual_blending]
+      #
+      # Path resolution uses segments derived from the class namespace:
+      #   Legion::Extensions::Github            → Settings[:extensions][:github]
+      #   Legion::Extensions::Agentic::Learning → Settings[:extensions][:agentic][:learning]
+      #   Legion::Extensions::MicrosoftTeams    → Settings[:extensions][:microsoft_teams]
+      #   Legion::Extensions::Llm::Openai       → Settings[:extensions][:llm][:openai]
       def settings
-        ext_key = derive_settings_key
-        if Legion::Settings[:extensions]&.key?(ext_key)
-          Legion::Settings[:extensions][ext_key]
-        else
-          {}
-        end
+        segments = derive_settings_segments
+        dig_or_create(Legion::Settings[:extensions], segments)
       end
 
       private
 
-      def derive_settings_key
-        if respond_to?(:lex_filename)
-          fname = lex_filename
-          (fname.is_a?(Array) ? fname.first : fname).to_sym
-        else
-          derive_settings_key_from_class
-        end
+      # Derives the gem-level segments from the class namespace.
+      # Stops at NAMESPACE_BOUNDARIES so sub-modules (Runners, Actors, etc.)
+      # resolve to their parent extension, not deeper.
+      #
+      # Legion::Extensions::Agentic::Learning::ConceptualBlending::Runners::Blend
+      #   → ['agentic', 'learning'] (stops at ConceptualBlending because next is Runners)
+      #
+      # Legion::Extensions::Agentic::Learning::ConceptualBlending
+      #   → ['agentic', 'learning'] (stops at ConceptualBlending — it's a sub-module, not a segment)
+      #
+      # Wait — ConceptualBlending IS a namespace part, not a boundary word.
+      # The gem is lex-agentic-learning → segments are ['agentic', 'learning'].
+      # ConceptualBlending is INSIDE the gem, not part of the gem name.
+      # So we need to know the gem's segment count to stop there.
+      #
+      # Strategy: if the caller responds to :segments (LegionIO's Base mixin),
+      # use those directly. Otherwise derive from namespace, stopping at
+      # boundary words or after 2 levels (covers most lex-X-Y patterns).
+      def derive_settings_segments
+        # Prefer explicit segments from LegionIO's Helpers::Base
+        return segments.map { |s| s.to_s.to_sym } if respond_to?(:segments)
+
+        derive_segments_from_class
       end
 
-      def derive_settings_key_from_class
+      def derive_segments_from_class
         name = respond_to?(:ancestors) ? ancestors.first.to_s : self.class.to_s
         parts = name.split('::')
         ext_idx = parts.index('Extensions')
-        target = if ext_idx && parts[ext_idx + 1]
-                   parts[ext_idx + 1]
-                 else
-                   parts.last
-                 end
-        target.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-              .downcase
-              .to_sym
+        return [camelize_to_snake(parts.last).to_sym] unless ext_idx
+
+        segment_parts = []
+        ((ext_idx + 1)...parts.length).each do |i|
+          break if NAMESPACE_BOUNDARIES.include?(parts[i])
+
+          segment_parts << camelize_to_snake(parts[i]).to_sym
+        end
+
+        # The gem-level segments are the parts between Extensions:: and
+        # the first sub-module that isn't part of the gem name.
+        # For lex-agentic-learning, gem segments = [:agentic, :learning].
+        # ConceptualBlending is a sub-module INSIDE the gem.
+        # We use the registered extension entry to find the correct depth,
+        # falling back to all segments if no registry entry exists.
+        resolve_gem_segments(segment_parts)
+      end
+
+      def resolve_gem_segments(all_segments)
+        return all_segments if all_segments.length <= 1
+
+        # Check if Settings::Extensions has this extension registered
+        # with known segments — use those as the authoritative gem boundary.
+        if defined?(Legion::Settings::Extensions)
+          # Try progressively shorter segment paths to find the registered gem
+          all_segments.length.downto(1) do |len|
+            candidate = all_segments[0, len]
+            gem_name = "lex-#{candidate.join('-')}"
+            entry = Legion::Settings::Extensions.find_extension(gem_name)
+            return candidate if entry
+          end
+        end
+
+        all_segments
+      end
+
+      # Digs into a nested hash using segments as keys, creating
+      # Concurrent::Hash at each level if missing.
+      def dig_or_create(root, segments)
+        return Concurrent::Hash.new unless root.is_a?(Hash)
+
+        segments.reduce(root) do |current, key|
+          if current.is_a?(Hash) && current.key?(key)
+            current[key]
+          elsif current.is_a?(Hash)
+            empty = Concurrent::Hash.new
+            current[key] = empty
+            empty
+          else
+            return Concurrent::Hash.new
+          end
+        end
+      end
+
+      def camelize_to_snake(str)
+        str.to_s
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .downcase
       end
     end
   end

data/lib/legion/settings/loader.rb

@@ -4,9 +4,11 @@ require 'resolv'
 require 'socket'
 require 'digest'
 require 'tmpdir'
+require 'concurrent/hash'
 require 'legion/logging'
 require 'legion/settings/os'
 require_relative 'dns_bootstrap'
+require_relative 'deep_merge'
 
 module Legion
   module Settings
@@ -47,7 +49,7 @@ module Legion
       def dns_defaults
         resolv_config = read_resolv_config
         {
-          fqdn:           detect_fqdn,
+          fqdn:           nil, # lazy — resolved on first access via resolve_fqdn!
           default_domain: resolv_config[:search_domains]&.first,
           search_domains: resolv_config[:search_domains] || [],
           nameservers:    resolv_config[:nameservers] || [],
@@ -55,6 +57,15 @@ module Legion
         }
       end
 
+      # Lazily resolve the FQDN on first access instead of blocking at init.
+      #
+      # @return [String, nil] the fully qualified domain name, or nil
+      def resolve_fqdn!
+        return @settings[:dns][:fqdn] if @settings.dig(:dns, :fqdn)
+
+        @settings[:dns][:fqdn] = detect_fqdn
+      end
+
       def client_defaults
         {
           hostname: system_hostname,
@@ -64,64 +75,25 @@ module Legion
         }
       end
 
-      def logging_defaults
-        {
-          level:       'info',
-          format:      'text',
-          log_file:    './legionio/logs/legion.log',
-          log_stdout:  true,
-          trace:       true,
-          async:       true,
-          include_pid: false,
-          transport:   {
-            enabled:            true,
-            forward_logs:       true,
-            forward_exceptions: true
-          }
-        }
-      end
-
-      def absorbers_defaults
-        {
-          enabled:   true,
-          max_depth: 5,
-          sources:   {
-            meetings:    {
-              enabled:          true,
-              include_chat:     true,
-              include_files:    true,
-              retention_days:   90,
-              min_duration_min: 5
-            },
-            email_inbox: {
-              enabled:      false,
-              folder:       'inbox',
-              max_age_days: 30
-            },
-            github:      {
-              enabled: true,
-              events:  %w[pull_request issues]
-            },
-            files:       {
-              enabled:    true,
-              watch_dirs: [],
-              extensions: %w[pdf docx txt md pptx rtf]
-            }
-          }
-        }
-      end
+      # No more per-module defaults methods in the Loader.
+      # Tier 1 deps (json, logging) are called directly in default_settings.
+      # Tier 2 libraries (transport, cache, etc.) self-register via
+      # Legion::Settings.register_library when they load.
 
       def default_settings
         {
+          # --- Tier 1: gemspec dependencies (always installed with legion-settings) ---
+          # legion-logging: always available, has Settings.default
+          logging:                    Legion::Logging::Settings.default,
+          # legion-json: always available, no Settings module yet — stub
+          # until legion-json adds Legion::JSON::Settings.default
+          json:                       Concurrent::Hash.new,
+
+          # --- Structural: owned by legion-settings itself ---
           client:                     client_defaults,
-          cluster:                    { public_keys: {} },
-          crypt:                      {
-            cluster_secret:         nil,
-            cluster_secret_timeout: 5,
-            vault:                  { connected: false }
-          },
-          cache:                      { enabled: true, connected: false, driver: 'dalli' },
-          extensions:                 {
+          cluster:                    Concurrent::Hash.new,
+          dns:                        dns_defaults,
+          extensions:                 Concurrent::Hash[
             core:               %w[
               lex-node lex-tasker lex-scheduler lex-health lex-ping
               lex-telemetry lex-metering lex-log lex-audit
@@ -140,20 +112,25 @@ module Legion
             reserved_words:     %w[transport cache crypt data settings json logging llm rbac legion],
             agentic:            { allowed: nil, blocked: [] },
             parallel_pool_size: 24
-          },
+          ],
           reload:                     false,
           reloading:                  false,
           auto_install_missing_lex:   true,
           default_extension_settings: {},
-          logging:                    logging_defaults,
-          absorbers:                  absorbers_defaults,
-          transport:                  { connected: false },
-          data:                       { connected: false },
           role:                       { profile: nil, extensions: [] },
           region:                     { current: nil, primary: nil, failover: nil, peers: [],
                                         default_affinity: 'any', data_residency: {} },
           process:                    { role: 'full' },
-          dns:                        dns_defaults
+
+          # --- Tier 2: stubs for libraries that self-register via register_library ---
+          # These ensure Settings[:key] returns a hash (not nil) before
+          # the owning library loads. The library replaces these with its
+          # full defaults when it calls Legion::Settings.register_library.
+          absorbers:                  Concurrent::Hash.new,
+          cache:                      Concurrent::Hash.new,
+          crypt:                      Concurrent::Hash.new,
+          data:                       Concurrent::Hash.new,
+          transport:                  Concurrent::Hash.new
         }
       end
 
@@ -165,12 +142,26 @@ module Legion
         @settings
       end
 
+      # Direct key lookup — does NOT trigger indifferent_access! rebuild.
+      # This is the hot path called by every Settings[:key] access.
+      # Supports both symbol and string keys without converting the whole tree.
       def [](key)
-        to_hash[key]
+        result = @settings[key]
+        return result unless result.nil? && key.is_a?(String)
+
+        @settings[key.to_sym]
       end
 
+      # Direct nested lookup — does NOT trigger indifferent_access! rebuild.
       def dig(*keys)
-        to_hash.dig(*keys)
+        keys.reduce(self) do |current, key|
+          return nil unless current.respond_to?(:[])
+
+          value = current.is_a?(Loader) ? current[key] : (current[key] || current[key.to_s])
+          return nil if value.nil? && !current.is_a?(Loader)
+
+          value
+        end
       end
 
       def []=(key, value)
@@ -376,29 +367,15 @@ module Legion
 
       def read_config_file(file)
         contents = File.read(file).dup
-        if contents.respond_to?(:force_encoding)
-          encoding = ::Encoding::ASCII_8BIT
-          contents = contents.force_encoding(encoding)
-          bom = (+"\xEF\xBB\xBF").force_encoding(encoding)
-          contents.sub!(bom, '')
-        else
-          contents.sub!(/^\357\273\277/, '')
-        end
+        encoding = ::Encoding::ASCII_8BIT
+        contents = contents.force_encoding(encoding)
+        bom = (+"\xEF\xBB\xBF").force_encoding(encoding)
+        contents.sub!(bom, '')
         contents.strip
       end
 
       def deep_merge(hash_one, hash_two)
-        merged = hash_one.dup
-        hash_two.each do |key, value|
-          merged[key] = if hash_one[key].is_a?(Hash) && value.is_a?(Hash)
-                          deep_merge(hash_one[key], value)
-                        elsif hash_one[key].is_a?(Array) && value.is_a?(Array)
-                          hash_one[key].concat(value).uniq
-                        else
-                          value
-                        end
-        end
-        merged
+        DeepMerge.deep_merge(hash_one, hash_two)
       end
 
       def create_loaded_tempfile!

data/lib/legion/settings/overlay.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'legion/settings/deep_merge'
+
 module Legion
   module Settings
     # Thread-local request-scoped settings overlay.
@@ -38,6 +40,13 @@ module Legion
           Thread.current[THREAD_KEY]
         end
 
+        # Returns true when a thread-local overlay is active.
+        #
+        # @return [Boolean]
+        def active?
+          !Thread.current[THREAD_KEY].nil?
+        end
+
         # Clear the thread-local overlay for the current thread.
         def clear_overlay!
           Thread.current[THREAD_KEY] = nil
@@ -61,16 +70,7 @@ module Legion
         private
 
         def deep_merge(base, overrides)
-          result = base.dup
-          overrides.each do |key, value|
-            existing = result[key]
-            result[key] = if existing.is_a?(Hash) && value.is_a?(Hash)
-                            deep_merge(existing, value)
-                          else
-                            value
-                          end
-          end
-          result
+          DeepMerge.deep_merge(base, overrides)
         end
       end
     end

data/lib/legion/settings/project_env.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'legion/logging'
+require 'legion/settings/deep_merge'
 
 module Legion
   module Settings
@@ -106,14 +107,7 @@ module Legion
         end
 
         def deep_merge_into!(base, overrides)
-          overrides.each do |key, value|
-            if base[key].is_a?(Hash) && value.is_a?(Hash)
-              deep_merge_into!(base[key], value)
-            else
-              base[key] = value
-            end
-          end
-          base
+          DeepMerge.deep_merge!(base, overrides)
         end
       end
     end

data/lib/legion/settings/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Settings
-    VERSION = '1.3.27'
+    VERSION = '1.4.0'
   end
 end

data/lib/legion/settings.rb

@@ -10,6 +10,8 @@ require 'legion/settings/validation_error'
 require 'legion/settings/helper'
 require 'legion/settings/overlay'
 require 'legion/settings/project_env'
+require 'legion/settings/extensions'
+require 'legion/settings/deep_merge'
 
 module Legion
   module Settings
@@ -56,6 +58,10 @@ module Legion
       def [](key)
         logger.info('Legion::Settings was not loaded, auto-loading now') if @loader.nil?
         load if @loader.nil?
+
+        # Fast path: skip overlay resolution when no overlay is active
+        return @loader[key] unless Overlay.active?
+
         overlay_val = Overlay.overlay_for(key)
         base_val = @loader[key]
         if overlay_val.is_a?(Hash) && base_val.is_a?(Hash)
@@ -97,7 +103,22 @@ module Legion
         thing[key.to_sym] = hash
         @loader.load_module_settings(thing)
         schema.register(key.to_sym, hash)
-        validate_module_on_merge(key.to_sym)
+        # Validation deferred to validate! — don't validate on every merge during boot
+      end
+
+      # Clean hook for legion-* core libraries to register their defaults.
+      # Called at the bottom of the library's settings.rb file.
+      # Library defaults fill in gaps; user JSON config wins.
+      # Idempotent — calling twice with the same key is safe.
+      #
+      # Usage in legion-transport/lib/legion/transport/settings.rb:
+      #   Legion::Settings.register_library(:transport, Legion::Transport::Settings.default)
+      def register_library(key, defaults)
+        sym = key.to_sym
+        return if @registered_libraries&.include?(sym)
+
+        merge_settings(sym, defaults)
+        (@registered_libraries ||= []) << sym
       end
 
       def define_schema(key, overrides)
@@ -292,6 +313,7 @@ module Legion
         @loaded = nil
         @schema = nil
         @cross_validations = nil
+        @registered_libraries = nil
         @reload_callbacks = nil
         @reload_mutex = nil
         @reload_flag = nil
@@ -311,16 +333,7 @@ module Legion
       end
 
       def deep_merge_for_overlay(base, overlay)
-        result = base.dup
-        overlay.each do |key, value|
-          existing = result[key]
-          result[key] = if existing.is_a?(Hash) && value.is_a?(Hash)
-                          deep_merge_for_overlay(existing, value)
-                        else
-                          value
-                        end
-        end
-        result
+        DeepMerge.deep_merge(base, overlay)
       end
 
       def ensure_loader

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-settings
 version: !ruby/object:Gem::Version
-  version: 1.3.27
+  version: 1.4.0
 platform: ruby
 authors:
 - Esity
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: legion-json
   requirement: !ruby/object:Gem::Requirement
@@ -65,7 +79,12 @@ files:
 - legion-settings.gemspec
 - lib/legion/settings.rb
 - lib/legion/settings/agent_loader.rb
+- lib/legion/settings/deep_merge.rb
 - lib/legion/settings/dns_bootstrap.rb
+- lib/legion/settings/extensions.rb
+- lib/legion/settings/extensions/filter.rb
+- lib/legion/settings/extensions/normalizer.rb
+- lib/legion/settings/extensions/store.rb
 - lib/legion/settings/helper.rb
 - lib/legion/settings/loader.rb
 - lib/legion/settings/os.rb