legion-settings 1.3.24 → 1.3.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 482b26bda825959da123ce4b68f0503181bbc05a2af3bbbbc912d067e76ae2cb
-  data.tar.gz: 45c70811a101925a22ec51244b6f8e42e1ad9d8cacc02eb8374c56eb11b6a9da
+  metadata.gz: a4d1e8b1f3f0f96ee8db9d11604d914fc253e430827e37f7e30cc244151dc75b
+  data.tar.gz: 1ed13e9f16b97fc33acc72e484671794210ac4750aef5502fc86e685ec2f9324
 SHA512:
-  metadata.gz: b063262f1a803400f2d86fbdbfe62d7778f9c2c8f01bd78baf73d74216b25417c4ae53791cacced67024bad384d4e3d3fab5239b729d568f636496f6a5b43170
-  data.tar.gz: b8d8c69b34ef0688e2d82b7ad88a175c59ee2dfb48f64267fa409ad26b29ae7394213f0947a6da73c07479f5df65390f75e15f602957eab031aeee14be261c59
+  metadata.gz: 47ab18a67eef8c35d86e52e9deec5716916754e5a84e0faec1ba3bbed4f24e9f4bb5c7749268eee23c96056ce85ef11c47787ac2df06fa5b918365730ddf6926
+  data.tar.gz: c76877c9e9a19f44c33a816a0580c265f721fe6dd0ef486eb06ec377ac6aedd5ae60fe52b4aaf4d8feb59bb18527f6127da40a0611d27718de3be63af5581b97

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Legion::Settings Changelog
 
+## [1.3.26] - 2026-04-02
+
+### Changed
+- Added a runtime dependency on `legion-logging >= 1.4.0` and moved `Settings`, `Loader`, `Resolver`, `ProjectEnv`, and `AgentLoader` onto component-aware logging helpers
+- Added `Legion::Logging::Helper` integration to top-level `Settings` access and DNS bootstrap logging so component tags and per-component levels apply consistently
+- `extensions.default_extension_settings` now defaults to `{}` instead of injecting a synthetic logger config
+- `Legion::Settings::Helper#settings` now returns `{}` when an extension has no explicit settings
+- `region.default_affinity` now defaults to `any`
+- `[]`, `dig`, and no-arg `load` now share the same project-env-aware load path, and the README now documents the actual `load`/`Loader.default_directories` split
+
+### Fixed
+- `validate!` now clears stale validation errors before rebuilding state, and nested schema branches now fail when a hash-shaped setting is replaced with a scalar
+- Loader mutation paths now invalidate indifferent-access and digest caches consistently, `load_module_default` no longer overwrites existing scalar settings, and resolver traversal now handles arrays of hashes
+- `Resolver` now treats clustered Vault connectivity from `Legion::Crypt` as available for `vault://` resolution instead of relying only on the top-level `crypt.vault.connected` flag
+- Logger-backed settings code paths now use consistent `log.debug/info/warn/error` behavior instead of mixed direct `Legion::Logging.*` calls
+
+## [1.3.25] - 2026-03-31
+
+### Added
+- `Settings.with_overlay(overrides) { }` — thread-local request-scoped settings overlay for per-tenant LLM routing without node restarts; nestable, cleans up via ensure block (closes #9)
+- `Settings.load_project_env(start_dir:)` — discovers and loads `.legionio.env` from Dir.pwd upward; dot-notation keys (`llm.default_model=haiku`) map to nested settings paths; auto-called during `Settings.load` (closes #10)
+- `Legion::Settings::Overlay` module — thread-local overlay storage with `with_overlay`, `current_overlay`, `overlay_for`, `clear_overlay!`
+- `Legion::Settings::ProjectEnv` module — env file discovery, parsing, and merging
+- Resolution order: request overlay > project `.legionio.env` > global settings
+- 44 new specs covering overlay scoping/nesting/cleanup, thread isolation, `.legionio.env` parsing, discovery, key mapping, and resolution order
+
 ## [1.3.24] - 2026-03-30
 
 ### Added

data/Gemfile

@@ -10,5 +10,6 @@ group :test do
   gem 'rspec'
   gem 'rspec_junit_formatter'
   gem 'rubocop'
+  gem 'rubocop-legion'
   gem 'simplecov'
 end

data/README.md

@@ -2,7 +2,7 @@
 
 Configuration management module for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Loads settings from JSON files, directories, and environment variables. Provides a unified `Legion::Settings[:key]` accessor used by all other Legion gems.
 
-**Version**: 1.3.22
+**Version**: 1.3.26
 
 ## Installation
 
@@ -21,20 +21,28 @@ gem 'legion-settings'
 ```ruby
 require 'legion/settings'
 
-Legion::Settings.load(config_dir: './')  # loads all .json files in the directory
+Legion::Settings.load                          # loads defaults, env, DNS bootstrap, and nearest .legionio.env
+Legion::Settings.load(config_dir: './settings') # also loads all .json files in the directory
 
 Legion::Settings[:client][:hostname]
-Legion::Settings[:transport][:connection][:host]
+Legion::Settings.dig(:transport, :connection, :host)
 ```
 
-### Config Paths (checked in order)
+`[]` and `dig` will auto-load settings on first access, and implicit access follows the same overlay/project-env/base precedence as explicit `load`.
 
-1. `/etc/legionio/`
-2. `~/.legionio/settings/`
-3. `~/legionio/`
-4. `./settings/`
+### Config Loading
 
-Each Legion module registers its own defaults via `merge_settings` during startup.
+`Legion::Settings.load` only consumes the paths you pass via `config_file`, `config_dir`, or `config_dirs`.
+
+If a caller wants the canonical Legion search directories, use `Legion::Settings::Loader.default_directories`:
+
+1. `~/.legionio/settings`
+2. `/etc/legionio/settings` on Unix-like systems
+3. `%APPDATA%\\legionio\\settings` on Windows when `APPDATA` is present
+
+`LegionIO` uses those directories during daemon boot. Library consumers can choose to pass any directory set they want.
+
+Each Legion module registers its own defaults via `merge_settings` during startup, and the nearest `.legionio.env` file is merged on top of base settings. Request overlays applied through `with_overlay` take highest precedence.
 
 ### Secret Resolution
 
@@ -76,25 +84,25 @@ Legion::Settings.validate!  # raises ValidationError if any settings are invalid
 
 # In development, warn instead of raising:
 # Set LEGION_DEV=true or Legion::Settings.set_prop(:dev, true)
-# validate! will warn to $stderr (or Legion::Logging) instead of raising
+# validate! will warn through the configured logger instead of raising
 ```
 
 ### Logging Defaults
 
-The `logging` key includes a `transport` sub-section (new in 1.3.22) that controls whether log events are forwarded over the message bus:
+The `logging` key includes a `transport` sub-section that controls whether log events are forwarded over the message bus:
 
 ```json
 {
   "logging": {
     "level": "info",
     "format": "text",
-    "log_file": null,
+    "log_file": "./legionio/logs/legion.log",
     "log_stdout": true,
     "trace": true,
     "async": true,
     "include_pid": false,
     "transport": {
-      "enabled": false,
+      "enabled": true,
       "forward_logs": true,
       "forward_exceptions": true
     }
@@ -102,7 +110,7 @@ The `logging` key includes a `transport` sub-section (new in 1.3.22) that contro
 }
 ```
 
-When `transport.enabled` is `true`, log events and unhandled exceptions are published to the AMQP bus so a central log consumer can aggregate them. Disabled by default to avoid a dependency on `legion-transport` at boot.
+When `transport.enabled` is `true`, log events and unhandled exceptions are published to the AMQP bus so a central log consumer can aggregate them.
 
 ## Requirements
 

data/legion-settings.gemspec

@@ -27,4 +27,5 @@ Gem::Specification.new do |spec|
   }
 
   spec.add_dependency 'legion-json', '>= 1.2.0'
+  spec.add_dependency 'legion-logging', '>= 1.5.0'
 end

data/lib/legion/settings/agent_loader.rb

@@ -2,10 +2,13 @@
 
 require 'yaml'
 require 'json'
+require 'legion/logging'
 
 module Legion
   module Settings
     module AgentLoader
+      extend Legion::Logging::Helper
+
       EXTENSIONS = %w[.yaml .yml .json].freeze
       GLOB = '*.{yaml,yml,json}'
 
@@ -44,12 +47,17 @@ module Legion
 
         private
 
+        def resolve_logger_settings
+          raw_logging = Legion::Settings.loader&.settings&.dig(:logging) if Legion::Settings.respond_to?(:loader)
+          raw_logging.is_a?(Hash) ? raw_logging : Legion::Logging::Settings.default
+        end
+
         def log_debug(message)
-          Legion::Logging.debug(message) if defined?(Legion::Logging)
+          log.debug(message)
         end
 
         def log_warn(message)
-          defined?(Legion::Logging) ? Legion::Logging.warn(message) : warn(message)
+          log.warn(message)
         end
       end
     end

data/lib/legion/settings/dns_bootstrap.rb

@@ -5,10 +5,13 @@ require 'json'
 require 'net/http'
 require 'resolv'
 require 'uri'
+require 'legion/logging'
 
 module Legion
   module Settings
     class DnsBootstrap
+      include Legion::Logging::Helper
+
       CACHE_FILENAME = '_dns_bootstrap.json'
       HOSTNAME_PREFIX = 'legion-bootstrap'
       URL_PATH = '/legion/bootstrap.json'
@@ -28,7 +31,7 @@ module Legion
         Resolv.getaddress(@hostname)
         true
       rescue Resolv::ResolvError, Resolv::ResolvTimeout => e
-        log_debug("Legion::Settings::DnsBootstrap#resolve? could not resolve #{@hostname}: #{e.message}")
+        log.debug("Legion::Settings::DnsBootstrap#resolve? could not resolve #{@hostname}: #{e.message}")
         false
       end
 
@@ -45,7 +48,7 @@ module Legion
 
         ::JSON.parse(response.body, symbolize_names: true)
       rescue StandardError => e
-        log_warn("DNS bootstrap fetch failed for #{@url}: #{e.message}")
+        log.warn("DNS bootstrap fetch failed for #{@url}: #{e.message}")
         nil
       end
 
@@ -67,11 +70,11 @@ module Legion
         return nil unless File.exist?(@cache_path)
 
         raw = ::JSON.parse(File.read(@cache_path), symbolize_names: true)
-        log_debug("DNS bootstrap cache hit: #{@cache_path}")
+        log.debug("DNS bootstrap cache hit: #{@cache_path}")
         raw.delete(:_dns_bootstrap_meta)
         raw
       rescue ::JSON::ParserError
-        log_warn("DNS bootstrap cache corrupt, deleting: #{@cache_path}")
+        log.warn("DNS bootstrap cache corrupt, deleting: #{@cache_path}")
         FileUtils.rm_f(@cache_path)
         nil
       end
@@ -82,12 +85,9 @@ module Legion
 
       private
 
-      def log_debug(message)
-        Legion::Logging.debug(message) if defined?(Legion::Logging)
-      end
-
-      def log_warn(message)
-        defined?(Legion::Logging) ? Legion::Logging.warn(message) : warn(message)
+      def resolve_logger_settings
+        raw_logging = Legion::Settings.loader&.settings&.dig(:logging) if Legion::Settings.respond_to?(:loader)
+        raw_logging.is_a?(Hash) ? raw_logging : Legion::Logging::Settings.default
       end
     end
   end

data/lib/legion/settings/helper.rb

@@ -8,7 +8,7 @@ module Legion
         if Legion::Settings[:extensions]&.key?(ext_key)
           Legion::Settings[:extensions][ext_key]
         else
-          { logger: { level: 'info', extended: false, internal: false } }
+          {}
         end
       end
 

data/lib/legion/settings/loader.rb

@@ -2,6 +2,9 @@
 
 require 'resolv'
 require 'socket'
+require 'digest'
+require 'tmpdir'
+require 'legion/logging'
 require 'legion/settings/os'
 require_relative 'dns_bootstrap'
 
@@ -9,6 +12,7 @@ module Legion
   module Settings
     class Loader
       include Legion::Settings::OS
+      include Legion::Logging::Helper
 
       class Error < RuntimeError; end
       attr_reader :warnings, :errors, :loaded_files, :settings
@@ -36,6 +40,7 @@ module Legion
         @settings = default_settings
         @indifferent_access = false
         @loaded_files = []
+        log.debug('Initialized Legion::Settings::Loader with default settings')
       end
 
       def dns_defaults
@@ -138,16 +143,14 @@ module Legion
           reload:                     false,
           reloading:                  false,
           auto_install_missing_lex:   true,
-          default_extension_settings: {
-            logger: { level: 'info', trace: false, extended: false }
-          },
+          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: 'prefer_local', data_residency: {} },
+                                        default_affinity: 'any', data_residency: {} },
           process:                    { role: 'full' },
           dns:                        dns_defaults
         }
@@ -171,7 +174,7 @@ module Legion
 
       def []=(key, value)
         @settings[key] = value
-        @indifferent_access = false
+        mark_dirty!
       end
 
       def hexdigest
@@ -220,16 +223,14 @@ module Legion
         mod_name = config.keys.first
         log_debug("Loading module settings: #{mod_name}")
         @settings = deep_merge(config, @settings)
-        @indifferent_access = false
+        mark_dirty!
       end
 
       def load_module_default(config)
         mod_name = config.keys.first
         log_debug("Loading module defaults: #{mod_name}")
-        merged = deep_merge(@settings, config)
-        deep_diff(@settings, merged) unless @loaded_files.empty?
-        @settings = merged
-        @indifferent_access = false
+        @settings = deep_merge(config, @settings)
+        mark_dirty!
       end
 
       def load_file(file)
@@ -238,11 +239,10 @@ module Legion
           begin
             contents = read_config_file(file)
             config = contents.empty? ? {} : Legion::JSON.load(contents)
-            merged = deep_merge(@settings, config)
-            deep_diff(@settings, merged) unless @loaded_files.empty?
-            @settings = merged
-            # @indifferent_access = false
+            @settings = deep_merge(@settings, config)
+            mark_dirty!
             @loaded_files << file
+            log.debug("Loaded settings file #{file}")
           rescue Legion::JSON::ParseError => e
             log_error("config file must be valid json: #{file}")
             log_error("  parse error: #{e.message}")
@@ -255,7 +255,7 @@ module Legion
       def load_directory(directory)
         path = directory.gsub(/\\(?=\S)/, '/')
         if File.readable?(path) && File.executable?(path)
-          files = Dir.glob(File.join(path, '**{,/*/**}/*.json')).uniq
+          files = Dir.glob(File.join(path, '**', '*.json'))
           files.each { |file| load_file(file) }
           log_info("Settings: loaded directory #{path} (#{files.size} files)")
         else
@@ -268,7 +268,7 @@ module Legion
         if @settings[:client][:subscriptions].is_a?(Array)
           @settings[:client][:subscriptions] << "client:#{@settings[:client][:name]}"
           @settings[:client][:subscriptions].uniq!
-          @indifferent_access = false
+          mark_dirty!
         else
           log_warn('unable to apply legion client overrides, reason: client subscriptions is not an array')
         end
@@ -290,6 +290,11 @@ module Legion
 
       private
 
+      def resolve_logger_settings
+        raw_logging = instance_variable_defined?(:@settings) ? @settings&.[](:logging) : nil
+        raw_logging.is_a?(Hash) ? raw_logging : Legion::Logging::Settings.default
+      end
+
       def load_dns_from_cache(bootstrap)
         config = bootstrap.read_cache
         start_dns_background_refresh(bootstrap) if config
@@ -311,7 +316,7 @@ module Legion
           hostname:   bootstrap.hostname,
           url:        bootstrap.url
         }
-        @indifferent_access = false
+        mark_dirty!
       end
 
       def start_dns_background_refresh(bootstrap)
@@ -357,14 +362,14 @@ module Legion
         @settings[:api] ||= {}
         @settings[:api][:port] = ENV['LEGION_API_PORT'].to_i
         log_warn("using api port environment variable, api: #{@settings[:api]}")
-        @indifferent_access = false
+        mark_dirty!
       end
 
       def load_privacy_env
         return unless ENV['LEGION_ENTERPRISE_PRIVACY'] == 'true'
 
         @settings[:enterprise_data_privacy] = true
-        @indifferent_access = false
+        mark_dirty!
       end
 
       def read_config_file(file)
@@ -394,19 +399,6 @@ module Legion
         merged
       end
 
-      def deep_diff(hash_one, hash_two)
-        keys = hash_one.keys.concat(hash_two.keys).uniq
-        keys.each_with_object({}) do |key, diff|
-          next if hash_one[key] == hash_two[key]
-
-          diff[key] = if hash_one[key].is_a?(Hash) && hash_two[key].is_a?(Hash)
-                        deep_diff(hash_one[key], hash_two[key])
-                      else
-                        [hash_one[key], hash_two[key]]
-                      end
-        end
-      end
-
       def create_loaded_tempfile!
         dir = ENV['LEGION_LOADED_TEMPFILE_DIR'] || Dir.tmpdir
         file_name = "legion_#{legion_service_name}_loaded_files"
@@ -415,6 +407,15 @@ module Legion
         path
       end
 
+      public
+
+      def mark_dirty!
+        @indifferent_access = false
+        @hexdigest = nil
+      end
+
+      private
+
       def legion_service_name
         File.basename($PROGRAM_NAME).split('-').last
       end
@@ -422,7 +423,7 @@ module Legion
       def system_hostname
         Socket.gethostname
       rescue StandardError => e
-        Legion::Logging.debug("Legion::Settings::Loader#system_hostname failed: #{e.message}") if defined?(Legion::Logging)
+        log_debug("Legion::Settings::Loader#system_hostname failed: #{e.message}")
         'unknown'
       end
 
@@ -431,7 +432,7 @@ module Legion
         preferred = addresses.find { |a| rfc1918?(a.ip_address) }
         (preferred || addresses.first)&.ip_address || 'unknown'
       rescue StandardError => e
-        Legion::Logging.debug("Legion::Settings::Loader#system_address failed: #{e.message}") if defined?(Legion::Logging)
+        log_debug("Legion::Settings::Loader#system_address failed: #{e.message}")
         'unknown'
       end
 
@@ -442,19 +443,19 @@ module Legion
       end
 
       def log_info(message)
-        defined?(Legion::Logging) ? Legion::Logging.info(message) : $stdout.puts(message)
+        log.info(message)
       end
 
       def log_debug(message)
-        Legion::Logging.debug(message) if defined?(Legion::Logging)
+        log.debug(message)
       end
 
       def log_warn(message)
-        defined?(Legion::Logging) ? Legion::Logging.warn(message) : warn(message)
+        log.warn(message)
       end
 
       def log_error(message)
-        defined?(Legion::Logging) ? Legion::Logging.error(message) : warn(message)
+        log.error(message)
       end
 
       def warning(message, data = {})

data/lib/legion/settings/overlay.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Legion
+  module Settings
+    # Thread-local request-scoped settings overlay.
+    #
+    # Provides block-scoped overrides that sit above global settings in the
+    # resolution order: request overlay > project .legionio.env > global settings.
+    #
+    # Usage:
+    #   Legion::Settings.with_overlay(llm: { default_model: 'claude-3-haiku' }) do
+    #     Legion::Settings[:llm][:default_model]  # => 'claude-3-haiku'
+    #   end
+    #
+    # Overlays are nestable — inner overlay merges on top of the outer one.
+    module Overlay
+      THREAD_KEY = :legion_settings_overlay
+
+      class << self
+        # Execute a block with the given overrides active in the current thread.
+        # The overrides hash uses the same top-level key structure as Settings.
+        #
+        # @param overrides [Hash] settings to override for the duration of the block
+        # @yield block executed with the overlay active
+        # @return the return value of the block
+        def with_overlay(overrides)
+          previous = Thread.current[THREAD_KEY]
+          Thread.current[THREAD_KEY] = deep_merge(previous || {}, overrides)
+          yield
+        ensure
+          Thread.current[THREAD_KEY] = previous
+        end
+
+        # Return the current thread-local overlay hash, or nil if none is active.
+        #
+        # @return [Hash, nil]
+        def current_overlay
+          Thread.current[THREAD_KEY]
+        end
+
+        # Clear the thread-local overlay for the current thread.
+        def clear_overlay!
+          Thread.current[THREAD_KEY] = nil
+        end
+
+        # Resolve a top-level key against the active overlay, returning the
+        # overlay value (which may need to be merged with base) or nil when no
+        # overlay is set.
+        #
+        # @param key [Symbol, String]
+        # @return [Object, nil]
+        def overlay_for(key)
+          overlay = Thread.current[THREAD_KEY]
+          return nil unless overlay
+
+          sym_key = key.to_sym
+          str_key = key.to_s
+          overlay[sym_key] || overlay[str_key]
+        end
+
+        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
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/project_env.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'legion/logging'
+
+module Legion
+  module Settings
+    # Per-project `.legionio.env` config file loader.
+    #
+    # Walks up from Dir.pwd searching for a `.legionio.env` file.  When found,
+    # parses `KEY=VALUE` lines with dot-notation keys and merges them into the
+    # loader at a priority between global settings and the request overlay.
+    #
+    # File format:
+    #   # comment lines are ignored
+    #   llm.default_model=claude-sonnet-4-5-20241022
+    #   cache.driver=redis
+    #
+    # Keys use dot notation to address nested settings paths.
+    # Values are always strings; callers should coerce as needed.
+    #
+    # Resolution order (lowest → highest priority):
+    #   global settings < .legionio.env < request overlay (#9)
+    module ProjectEnv
+      extend Legion::Logging::Helper
+
+      ENV_FILENAME = '.legionio.env'
+
+      class << self
+        # Walk up from +start_dir+ (defaults to Dir.pwd) looking for
+        # `.legionio.env`.  Returns the first file found, or nil.
+        #
+        # @param start_dir [String, nil] directory to start the search from
+        # @return [String, nil] absolute path to the file, or nil
+        def find_project_env_file(start_dir: nil)
+          dir = File.expand_path(start_dir || Dir.pwd)
+          loop do
+            candidate = File.join(dir, ENV_FILENAME)
+            return candidate if File.file?(candidate) && File.readable?(candidate)
+
+            parent = File.dirname(dir)
+            break if parent == dir # filesystem root
+
+            dir = parent
+          end
+          nil
+        end
+
+        # Parse a `.legionio.env` file and return a nested hash of overrides.
+        #
+        # @param path [String] absolute path to the file
+        # @return [Hash] nested hash with symbol keys
+        def parse_env_file(path)
+          result = {}
+          File.readlines(path, chomp: true).each_with_index do |line, idx|
+            next if line.strip.empty?
+            next if line.strip.start_with?('#')
+
+            parts = line.split('=', 2)
+            unless parts.length == 2
+              log_warn("#{path}:#{idx + 1}: skipping malformed line (no '=' found)")
+              next
+            end
+
+            raw_key, value = parts
+            key_parts = raw_key.strip.split('.')
+            if key_parts.empty? || key_parts.any?(&:empty?)
+              log_warn("#{path}:#{idx + 1}: skipping invalid key '#{raw_key.strip}'")
+              next
+            end
+
+            set_nested(result, key_parts.map(&:to_sym), value.strip)
+          end
+          result
+        end
+
+        # Find and load the project env file into the given settings hash,
+        # merging overrides (env file values win over existing values).
+        #
+        # @param settings [Hash] the settings hash to merge into (mutated in place)
+        # @param start_dir [String, nil] directory to start searching from
+        # @return [String, nil] path to the loaded file, or nil if none found
+        def load_into(settings, start_dir: nil)
+          path = find_project_env_file(start_dir: start_dir)
+          return nil unless path
+
+          overrides = parse_env_file(path)
+          deep_merge_into!(settings, overrides)
+          log_debug("ProjectEnv: loaded #{path}")
+          path
+        end
+
+        private
+
+        def resolve_logger_settings
+          raw_logging = Legion::Settings.loader&.settings&.dig(:logging) if Legion::Settings.respond_to?(:loader)
+          raw_logging.is_a?(Hash) ? raw_logging : Legion::Logging::Settings.default
+        end
+
+        def set_nested(hash, keys, value)
+          *parents, leaf = keys
+          target = parents.reduce(hash) do |h, k|
+            h[k] ||= {}
+            h[k]
+          end
+          target[leaf] = value
+        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
+        end
+
+        def log_debug(message)
+          log.debug(message)
+        end
+
+        def log_warn(message)
+          log.warn(message)
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/resolver.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
+
 module Legion
   module Settings
     module Resolver
+      extend Legion::Logging::Helper
+
       VAULT_PATTERN  = %r{\Avault://(.+?)#(.+)\z}
       ENV_PATTERN    = %r{\Aenv://(.+)\z}
       LEASE_PATTERN  = %r{\Alease://(.+?)#(.+)\z}
@@ -81,60 +85,79 @@ module Legion
       end
 
       def count_vault_refs(hash)
-        return 0 unless hash.is_a?(Hash)
-
-        hash.sum do |_key, value|
-          case value
-          when String then value.match?(VAULT_PATTERN) ? 1 : 0
-          when Array  then value.count { |v| v.is_a?(String) && v.match?(VAULT_PATTERN) }
-          when Hash   then count_vault_refs(value)
-          else 0
-          end
+        case hash
+        when String then hash.match?(VAULT_PATTERN) ? 1 : 0
+        when Array  then hash.sum { |value| count_vault_refs(value) }
+        when Hash   then hash.sum { |_key, value| count_vault_refs(value) }
+        else 0
         end
       end
 
       def vault_connected?
         return false unless defined?(Legion::Crypt)
         return false unless defined?(Legion::Settings)
+        return Legion::Crypt.vault_connected? if Legion::Crypt.respond_to?(:vault_connected?)
 
-        Legion::Settings[:crypt][:vault][:connected] == true
+        Legion::Settings[:crypt][:vault][:connected] == true ||
+          (Legion::Crypt.respond_to?(:connected_clusters) && Legion::Crypt.connected_clusters.any?)
       rescue StandardError => e
         log_debug("Legion::Settings::Resolver#vault_connected? failed: #{e.message}")
         false
       end
 
-      def walk(hash, path:, &block)
-        hash.each do |key, value|
-          current_path = path.empty? ? key.to_s : "#{path}.#{key}"
-
-          case value
-          when Hash
-            walk(value, path: current_path, &block)
-          when String
-            next unless value.match?(URI_PATTERN)
-
-            resolved = resolve_single(value)
-            if resolved.nil?
-              log_warn("Settings resolver: could not resolve #{current_path} (#{value})")
-              block&.call(:unresolved)
-            else
-              hash[key] = resolved
-              register_lease_ref(value, current_path) if value.match?(LEASE_PATTERN)
-              block&.call(:resolved)
-            end
-          when Array
-            next unless resolvable_chain?(value)
-
-            resolved = resolve_chain(value)
-            if resolved.nil?
-              log_warn("Settings resolver: fallback chain exhausted for #{current_path}")
-              block&.call(:unresolved)
-            else
-              hash[key] = resolved
-              register_lease_refs_from_chain(value, current_path)
-              block&.call(:resolved)
-            end
+      def walk(hash, path:, &)
+        case hash
+        when Hash
+          hash.each do |key, value|
+            current_path = path.empty? ? key.to_s : "#{path}.#{key}"
+            walk_value(hash, key, value, current_path, &)
+          end
+        when Array
+          hash.each_with_index do |value, index|
+            current_path = "#{path}[#{index}]"
+            walk_value(hash, index, value, current_path, &)
+          end
+        end
+      end
+
+      def walk_value(container, key, value, current_path, &)
+        case value
+        when Hash
+          walk(value, path: current_path, &)
+        when String
+          handle_string_value(container, key, value, current_path) { |status| yield(status) if block_given? }
+        when Array
+          handle_array_value(container, key, value, current_path) { |status| yield(status) if block_given? }
+        end
+      end
+
+      def handle_string_value(container, key, value, current_path)
+        return unless value.match?(URI_PATTERN)
+
+        resolved = resolve_single(value)
+        if resolved.nil?
+          log_warn("Settings resolver: could not resolve #{current_path} (#{value})")
+          yield(:unresolved) if block_given?
+        else
+          container[key] = resolved
+          register_lease_ref(value, current_path) if value.match?(LEASE_PATTERN)
+          yield(:resolved) if block_given?
+        end
+      end
+
+      def handle_array_value(container, key, value, current_path, &)
+        if resolvable_chain?(value) && value.all? { |entry| !entry.is_a?(Hash) && !entry.is_a?(Array) }
+          resolved = resolve_chain(value)
+          if resolved.nil?
+            log_warn("Settings resolver: fallback chain exhausted for #{current_path}")
+            yield(:unresolved) if block_given?
+          else
+            container[key] = resolved
+            register_lease_refs_from_chain(value, current_path)
+            yield(:resolved) if block_given?
           end
+        else
+          walk(value, path: current_path, &)
         end
       end
 
@@ -207,40 +230,29 @@ module Legion
       end
 
       def count_lease_refs(hash)
-        return 0 unless hash.is_a?(Hash)
-
-        hash.sum do |_key, value|
-          case value
-          when String then value.match?(LEASE_PATTERN) ? 1 : 0
-          when Array  then value.count { |v| v.is_a?(String) && v.match?(LEASE_PATTERN) }
-          when Hash   then count_lease_refs(value)
-          else 0
-          end
+        case hash
+        when String then hash.match?(LEASE_PATTERN) ? 1 : 0
+        when Array  then hash.sum { |value| count_lease_refs(value) }
+        when Hash   then hash.sum { |_key, value| count_lease_refs(value) }
+        else 0
         end
       end
 
+      def resolve_logger_settings
+        raw_logging = Legion::Settings.loader&.settings&.dig(:logging) if Legion::Settings.respond_to?(:loader)
+        raw_logging.is_a?(Hash) ? raw_logging : Legion::Logging::Settings.default
+      end
+
       def log_info(message)
-        if defined?(Legion::Logging)
-          Legion::Logging.info(message)
-        else
-          $stdout.puts(message)
-        end
+        log.info(message)
       end
 
       def log_warn(message)
-        if defined?(Legion::Logging)
-          Legion::Logging.warn(message)
-        else
-          warn(message)
-        end
+        log.warn(message)
       end
 
       def log_debug(message)
-        if defined?(Legion::Logging)
-          Legion::Logging.debug(message)
-        else
-          $stdout.puts(message)
-        end
+        log.debug(message)
       end
     end
   end

data/lib/legion/settings/schema.rb

@@ -113,7 +113,14 @@ module Legion
           if constraint.is_a?(Hash) && constraint.key?(:type)
             validate_leaf(constraint, value, mod_name, current_path, errors)
           elsif constraint.is_a?(Hash)
-            validate_node(constraint, value, mod_name, current_path, errors) if value.is_a?(Hash)
+            next if value.nil?
+
+            if value.is_a?(Hash)
+              validate_node(constraint, value, mod_name, current_path, errors)
+            else
+              errors << { module: mod_name, path: current_path,
+                          message: "expected Hash, got #{value.class} (#{value.inspect})" }
+            end
           end
         end
       end

data/lib/legion/settings/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Settings
-    VERSION = '1.3.24'
+    VERSION = '1.3.26'
   end
 end

data/lib/legion/settings.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 require 'legion/json'
+require 'legion/logging'
 require 'legion/settings/version'
 require 'legion/json/parse_error'
 require 'legion/settings/loader'
 require 'legion/settings/schema'
 require 'legion/settings/validation_error'
 require 'legion/settings/helper'
+require 'legion/settings/overlay'
+require 'legion/settings/project_env'
 
 module Legion
   module Settings
@@ -15,6 +18,8 @@ module Legion
     class << self
       attr_accessor :loader
 
+      include Legion::Logging::Helper
+
       def load(options = {})
         has_config = options[:config_file] || options[:config_dir] || options[:config_dirs]&.any?
 
@@ -35,6 +40,7 @@ module Legion
         end
 
         @loaded = true if has_config
+        load_project_env
         logger.info("Settings loaded from #{@loader.loaded_files.size} files")
         @loader
       end
@@ -48,19 +54,35 @@ module Legion
       end
 
       def [](key)
-        logger.info('Legion::Settings was not loading, auto loading now!') if @loader.nil?
-        ensure_loader
-        @loader[key]
+        logger.info('Legion::Settings was not loaded, auto-loading now') if @loader.nil?
+        load if @loader.nil?
+        overlay_val = Overlay.overlay_for(key)
+        base_val = @loader[key]
+        if overlay_val.is_a?(Hash) && base_val.is_a?(Hash)
+          deep_merge_for_overlay(base_val, overlay_val)
+        elsif !overlay_val.nil?
+          overlay_val
+        else
+          base_val
+        end
       rescue NoMethodError, TypeError => e
-        Legion::Logging.debug("Legion::Settings#[] key=#{key} failed: #{e.message}") if defined?(Legion::Logging)
+        logger.debug("Legion::Settings#[] key=#{key} failed: #{e.message}")
         nil
       end
 
       def dig(*keys)
-        ensure_loader
-        @loader.dig(*keys)
+        return nil if keys.empty?
+
+        logger.info('Legion::Settings was not loaded, auto-loading now') if @loader.nil?
+        load if @loader.nil?
+
+        root = self[keys.first]
+        return root if keys.length == 1
+        return nil unless root.respond_to?(:dig)
+
+        root.dig(*keys[1..])
       rescue NoMethodError, TypeError => e
-        Legion::Logging.debug("Legion::Settings#dig keys=#{keys.inspect} failed: #{e.message}") if defined?(Legion::Logging)
+        logger.debug("Legion::Settings#dig keys=#{keys.inspect} failed: #{e.message}")
         nil
       end
 
@@ -86,12 +108,36 @@ module Legion
         cross_validations << block
       end
 
+      # Execute a block with thread-local settings overrides active.
+      # Overlays are nestable — inner overlays merge on top of outer ones.
+      # Resolution order inside the block: overlay > project env > global settings.
+      #
+      # @param overrides [Hash] settings to override for the duration of the block
+      # @yield the block executed with the overlay active
+      # @return the return value of the block
+      def with_overlay(overrides, &)
+        Overlay.with_overlay(overrides, &)
+      end
+
+      # Load (or reload) the nearest `.legionio.env` file into the settings loader.
+      # Searches from Dir.pwd upward.  Env-file values take priority over global
+      # settings but are overridden by a request overlay (with_overlay).
+      #
+      # @param start_dir [String, nil] directory to start searching from (defaults to Dir.pwd)
+      # @return [String, nil] path to the loaded file, or nil if none found
+      def load_project_env(start_dir: nil)
+        ensure_loader
+        path = ProjectEnv.load_into(@loader.settings, start_dir: start_dir)
+        @loader.mark_dirty! if path
+        path
+      end
+
       def dev_mode?
         return true if ENV['LEGION_DEV'] == 'true'
 
         Legion::Settings[:dev] ? true : false
       rescue StandardError => e
-        Legion::Logging.debug("Legion::Settings#dev_mode? failed: #{e.message}") if defined?(Legion::Logging)
+        logger.debug("Legion::Settings#dev_mode? failed: #{e.message}")
         false
       end
 
@@ -100,7 +146,7 @@ module Legion
 
         Legion::Settings[:enterprise_data_privacy] ? true : false
       rescue StandardError => e
-        Legion::Logging.debug("Legion::Settings#enterprise_privacy? failed: #{e.message}") if defined?(Legion::Logging)
+        logger.debug("Legion::Settings#enterprise_privacy? failed: #{e.message}")
         false
       end
 
@@ -143,28 +189,39 @@ module Legion
         @loaded = nil
         @schema = nil
         @cross_validations = nil
+        Overlay.clear_overlay!
       end
 
       def logger
-        @logger = if ::Legion.const_defined?('Logging')
-                    ::Legion::Logging
-                  else
-                    require 'logger'
-                    l = ::Logger.new($stdout)
-                    l.formatter = proc do |severity, datetime, _progname, msg|
-                      "[#{datetime.strftime('%Y-%m-%d %H:%M:%S %z')}] #{severity} #{msg}\n"
-                    end
-                    l
-                  end
+        log
       end
 
       private
 
+      def resolve_logger_settings
+        raw_logging = @loader&.settings&.dig(:logging)
+        raw_logging.is_a?(Hash) ? raw_logging : Legion::Logging::Settings.default
+      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
+      end
+
       def ensure_loader
         return @loader if @loader
 
         @loader = Legion::Settings::Loader.new
         @loader.load_env
+        logger.debug('Initialized Legion::Settings loader without config files')
         @loader
       end
 
@@ -177,11 +234,7 @@ module Legion
         label = count == 1 ? 'error' : 'errors'
         message = "Legion::Settings dev mode: #{count} configuration #{label} detected (not raising):\n"
         message += errs.map { |e| "  [#{e[:module]}] #{e[:path]}: #{e[:message]}" }.join("\n")
-        if ::Legion.const_defined?('Logging')
-          ::Legion::Logging.warn(message)
-        else
-          warn(message)
-        end
+        logger.warn(message)
       end
 
       def validate_module_on_merge(mod_name)
@@ -193,6 +246,7 @@ module Legion
       end
 
       def revalidate_all_modules
+        @loader.errors.clear
         schema.registered_modules.each do |mod_name|
           values = @loader[mod_name]
           next unless values.is_a?(Hash)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-settings
 version: !ruby/object:Gem::Version
-  version: 1.3.24
+  version: 1.3.26
 platform: ruby
 authors:
 - Esity
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: legion-logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.0
 description: A gem written to handle LegionIO Settings in a consistent way across
   extensions
 email:
@@ -54,6 +68,8 @@ files:
 - lib/legion/settings/helper.rb
 - lib/legion/settings/loader.rb
 - lib/legion/settings/os.rb
+- lib/legion/settings/overlay.rb
+- lib/legion/settings/project_env.rb
 - lib/legion/settings/resolver.rb
 - lib/legion/settings/schema.rb
 - lib/legion/settings/validation_error.rb