legion-settings 1.4.0 → 1.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baf40211abee6a48e5863077ce8e31fa416afbad9f003933e7edcfca4b8a72ba
-  data.tar.gz: f8faf5fb5eadead569c9f222a70c58e5ac11bc923dc281bd587f3f2704125cd0
+  metadata.gz: 5b4ca4881211bedb39799998f075d8539d5ebfdf79178f2d6c61e9ee1ebd28db
+  data.tar.gz: fcf3c214190e2263cb67e4d17c5f8ddaceb478e5fed16a9a8021ed2722e4d160
 SHA512:
-  metadata.gz: 7dbe223a77152d41812ec94bd98457db0570dae8bdea879f58b4ec052fca03eed46d1364617d4affb73d4cd7bc0364e6f6074c5a0fe5d8c433776e900d354417
-  data.tar.gz: b362c5d3a541c5afce645b47656ef1a427b65d58500bd5100e14717451dacaa8024823a188fd97f2475cb2ab1e176912c30ed7ba0496f0f512dd79a593228401
+  metadata.gz: f3f2a51d7a7633bf404b5f965c374357abc4a70d5c9e8d69ebd1bee22dfd4b3c878a4ee3af9870d1a4d42fe471a973db3b9c765dca9fc835f105b8c6ecd8ce42
+  data.tar.gz: 34a30b2ec19e8c310c89a5c59b1d2b87ad01fddd09d5948738c3092cd6c5d77d86384a25aa1884bbe44fc27db288e929c1db863d2ef46b126b7b4d045e5c124b

data/.github/workflows/ci.yml

@@ -9,12 +9,16 @@ on:
 jobs:
   ci:
     uses: LegionIO/.github/.github/workflows/ci.yml@main
+    with:
+      companion-gems: ${{ github.event_name == 'pull_request' && '{"legion-crypt":{"repository":"LegionIO/legion-crypt","ref":"f22702285d9ad9d80ddab115cf93568583bd7211"}}' || '{}' }}
 
   lint:
     uses: LegionIO/.github/.github/workflows/lint-patterns.yml@main
 
   security:
     uses: LegionIO/.github/.github/workflows/security-scan.yml@main
+    with:
+      companion-gems: ${{ github.event_name == 'pull_request' && '{"legion-crypt":{"repository":"LegionIO/legion-crypt","ref":"f22702285d9ad9d80ddab115cf93568583bd7211"}}' || '{}' }}
 
   version-changelog:
     uses: LegionIO/.github/.github/workflows/version-changelog.yml@main

data/.gitignore

@@ -14,3 +14,4 @@
 # rspec failure tracking
 .rspec_status
 legionio.key
+/.ci-dependencies/

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Legion::Settings Changelog
 
+## [1.4.4] - 2026-10-31
+
+### Fixed
+- Lease rotation follows only the winning secret source, with typed paths through nested hashes and arrays.
+- Preserve source declarations across repeated resolution and rotations; retire bindings when sources change or destinations disappear.
+- Preserve lease declarations inside module-default arrays when normalizing the live settings tree, so reload can bind them again.
+- Publish hot-reloaded settings and lease references together, including equal-value source changes. Invalid files or unresolved secrets leave the active loader and bindings intact.
+- Keep Vault reads outside lease publication locks and scope read caches to each resolution.
+- Remove ambiguous backtracking from Vault and lease URI parsing while preserving existing delimiter semantics.
+- Accept extra keyword options in `Loader#load_file` while preserving the explicit `strict:` behavior.
+
+### Documentation
+- Clarify the process-local, shared in-memory settings model and its persistence, synchronization, and component-ownership boundaries.
+
+### Compatibility
+- Lease resolution requires `legion-crypt >= 1.5.38`; environment and literal-only settings remain usable without Crypt.
+
+## [1.4.3] - 2026-10-30
+
+### Fixed
+- Library registration idempotency now checks the active loader, allowing defaults to be registered after loader replacement without discarding user overrides.
+
+## [1.4.2] - 2026-08-14
+
+### Fixed
+- `Legion::Settings::Helper#settings` now resolves two-segment (nested) extensions to their nested settings path instead of a flat key. `lex-llm-vllm` (`Legion::Extensions::Llm::Vllm::Runners::DiscoveryRefresh`) resolves to `Legion::Settings[:extensions][:llm][:vllm]` — not the flat `:llm_vllm` key — and `lex-identity-entra` (`Legion::Extensions::Identity::Entra::Delegated::Runners::Login`) resolves to `[:extensions][:identity][:entra]`. All `lex-<a>-<b>` nested extensions (lex-llm-*, lex-identity-*, lex-agentic-*, etc.) were reading the wrong (empty) settings path in production; single-segment `lex-<name>` extensions were unaffected.
+- Resolution is now segment-based: an explicit `segments` method (LegionIO's `Helpers::Base` mixin) is preferred; otherwise segments are derived from the class namespace, stopping at boundary words (Actor/Actors/Runners/Helpers/Transport/Data), with the gem boundary verified against the `Legion::Settings::Extensions` registry. Sub-module runners resolve to their parent gem's settings.
+
+### Added
+- Regression spec in `spec/legion/settings/helper_spec.rb` covering nested two-segment runner resolution (lex-llm-vllm, lex-identity-entra) that fails on the 1.4.0 flat-key helper.
+
+### Changed
+- `Settings#[]` and `Settings#dig` read the settings hash directly with string→symbol key fallback instead of rebuilding an indifferent-access hash tree on every read (`indifferent_access!` now only runs on explicit `to_hash` calls) — removes the boot-time O(n) rebuild per read.
+- Overlay skips resolution when no overlay is active (fast path).
+- Consolidated four duplicate deep-merge implementations into a shared `Legion::Settings::DeepMerge` module that preserves `Concurrent::Hash` type through merges.
+- FQDN is lazy-resolved on first access instead of blocking at init; schema validation is deferred to `validate!` instead of running on every merge.
+
 ## [1.4.0] - 2026-04-29
 
 ### Added

data/Gemfile

@@ -4,6 +4,9 @@ source 'https://rubygems.org'
 
 gemspec
 group :test do
+  crypt_paths = [File.join(__dir__, '.ci-dependencies/legion-crypt'), File.expand_path('../legion-crypt', __dir__)]
+  crypt_path = crypt_paths.find { |path| File.directory?(path) && File.file?(File.join(path, 'legion-crypt.gemspec')) }
+  gem 'legion-crypt', '>= 1.5.38', **(crypt_path ? { path: crypt_path } : {})
   gem 'legion-logging'
   gem 'logger'
   gem 'rake'

data/README.md

@@ -1,8 +1,19 @@
 # legion-settings
 
-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.
+The process-local, in-memory settings store for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Loads settings from JSON files, directories, and environment variables into a shared settings tree, exposed through `Legion::Settings[:key]`.
 
-**Version**: 1.3.27
+**Version**: 1.4.4
+
+## Process-Local Settings Model
+
+Think of `legion-settings` as **one big, process-local `Concurrent::Hash`-style object**: the settings tree for that running Ruby process.
+
+- **Shared within the process.** Gems, extensions, actors, and worker threads use the same base settings tree through `Legion::Settings`, rather than maintaining separate copies of the application's configuration.
+- **Local to that process.** Another process has its own settings object, even on the same host or when loading the same files. Changing this process's settings does not update another process or node.
+- **Generic storage, component-owned meaning.** Each library owns its namespace, defaults, and behavior. Settings supplies common loading, merging, access, and reload mechanics; it does not own each component's execution policy.
+- **An in-memory object, not a persistence or synchronization service.** Files, environment variables, defaults, and resolved secrets populate the tree. Runtime changes do not automatically write back to those sources or broadcast to other processes.
+
+Request overlays provide scoped overrides without replacing the shared base tree. The `Concurrent::Hash`-style model does not mean every nested value is itself a concurrent hash or that an arbitrary sequence of reads and writes is atomic; callers must coordinate compound mutations.
 
 ## Installation
 
@@ -48,6 +59,8 @@ Each Legion module registers its own defaults via `merge_settings` during startu
 
 `Legion::Settings.reload!` re-reads the config files that were previously loaded, reapplies module defaults and the nearest `.legionio.env`, re-resolves secret references, and returns a hash describing the changed keys.
 
+Reload publishes the new loader and its lease bindings together. A source change is committed even when its resolved value is unchanged, so replacing a lease URI with the same literal bytes still stops rotation. Malformed files or unresolved secrets raise and leave the active loader and bindings intact.
+
 ```ruby
 changes = Legion::Settings.reload!
 
@@ -57,7 +70,7 @@ changes
 # }
 ```
 
-Callbacks run only when changes are detected:
+Callbacks run after publication, outside the reload and lease locks, and only when resolved values change:
 
 ```ruby
 Legion::Settings.on_reload do |changes|
@@ -113,9 +126,17 @@ Array values act as fallback chains — the first non-nil result wins:
 
 Call `Legion::Settings.resolve_secrets!` to resolve all URIs in-place. In the LegionIO boot sequence this is called automatically after `Legion::Crypt.start`. The `env://` scheme works even when Vault is not connected.
 
+Lease integration requires **legion-crypt 1.5.38 or newer** with **legion-settings 1.4.4 or newer**. Release Crypt first. Neither gem gains a runtime dependency on the other; environment and literal-only resolution work without Crypt.
+
+Only the winning lease in a fallback chain can rotate its destination. A winning environment, Vault, or literal value—including `false`—does not subscribe unused leases. Nested hashes and arrays use typed paths, so array indexes and keys containing dots are preserved.
+
+Repeated resolution reevaluates the retained source declarations, including after rotation. Editing a URI or changing a resolved value replaces its source; removing a destination retires its lease binding. A fresh reload treats file contents as new declarations rather than guessing provenance from matching secret values. Vault read caches are local to each resolution, and Vault reads finish before lease publication begins.
+
+An unresolved one-shot reference is logged and left unchanged; strict reload rejects unresolved references instead of replacing live settings.
+
 ```ruby
 Legion::Settings.resolve_secrets!
-# All vault://, env://, and lease:// references are now replaced with their resolved values
+# Resolvable vault://, env://, and lease:// references are replaced with their values
 ```
 
 ### Schema Validation
@@ -132,6 +153,17 @@ Legion::Settings.validate!  # raises ValidationError if any settings are invalid
 # validate! will warn through the configured logger instead of raising
 ```
 
+### Library Defaults
+
+Libraries own their defaults and register them with
+`Legion::Settings.register_library(:my_library, defaults)`. Existing configuration
+values take precedence. Registration is idempotent for the active loader; after
+replacing the loader or calling `load(force: true)`, a library can register its
+defaults again without losing configuration overrides.
+
+Settings and overlays are local to the process. Registration does not synchronize
+configuration across processes or provide durable shared state.
+
 ### Logging Defaults
 
 The `logging` key includes a `transport` sub-section that controls whether log events are forwarded over the message bus:

data/lib/legion/settings/loader.rb

@@ -226,7 +226,7 @@ module Legion
         mark_dirty!
       end
 
-      def load_file(file)
+      def load_file(file, strict: false, **)
         log.debug("Trying to load file #{file}")
         if File.file?(file) && File.readable?(file)
           begin
@@ -239,9 +239,11 @@ module Legion
           rescue Legion::JSON::ParseError => e
             log.error("config file must be valid json: #{file}")
             log.error("  parse error: #{e.message}")
+            raise if strict
           end
         else
           log.warn("Config file does not exist or is not readable file:#{file}")
+          raise Error, "Config file does not exist or is not readable: #{file}" if strict
         end
       end
 
@@ -337,10 +339,16 @@ module Legion
         end
       end
 
-      def with_indifferent_access(hash)
-        hash = indifferent_hash.merge(hash)
-        hash.each do |key, value|
-          hash[key] = with_indifferent_access(value) if value.is_a?(Hash)
+      def with_indifferent_access(value)
+        case value
+        when Hash
+          value.each_with_object(indifferent_hash) do |(key, child), result|
+            result[key] = with_indifferent_access(child)
+          end
+        when Array
+          value.map { |child| with_indifferent_access(child) }
+        else
+          value
         end
       end
 

data/lib/legion/settings/resolver.rb

@@ -1,81 +1,119 @@
 # frozen_string_literal: true
 
 require 'legion/logging'
+require 'weakref'
 
 module Legion
   module Settings
     module Resolver
       extend Legion::Logging::Helper
 
-      VAULT_PATTERN  = %r{\Avault://(.+?)#(.+)\z}
+      # The delimiter follows a nonempty path/name; subsequent path characters cannot consume it.
+      VAULT_PATTERN  = %r{\Avault://([^\n][^#\n]*)#([^\n]+)\z}
       ENV_PATTERN    = %r{\Aenv://(.+)\z}
-      LEASE_PATTERN  = %r{\Alease://(.+?)#(.+)\z}
+      LEASE_PATTERN  = %r{\Alease://([^\n][^#\n]*)#([^\n]+)\z}
       URI_PATTERN    = %r{\A(?:vault|env|lease)://}
 
+      @source_mutex = Mutex.new
+      @source_states = {}
+
       module_function
 
-      def resolve_secrets!(settings_hash)
+      def resolve_secrets!(settings_hash, owner: settings_hash, previous_owner: nil, strict: false, publish: nil)
         return settings_hash unless settings_hash.is_a?(Hash)
 
-        @vault_available = vault_connected?
-        @vault_cache     = {}
-
-        vault_count = count_vault_refs(settings_hash)
-        log.warn("Vault not connected — #{vault_count} vault:// reference(s) will not be resolved") if vault_count.positive? && !@vault_available
-
-        lease_count = count_lease_refs(settings_hash)
-        log.warn("LeaseManager not available — #{lease_count} lease:// reference(s) will not be resolved") if lease_count.positive? && !lease_manager_available?
+        state = resolution_state(owner: owner)
+        previous = previous_owner ? resolution_state(owner: previous_owner) : state
+        state[:mutex].synchronize do
+          context = { vault_available: vault_connected?, vault_cache: {}, sources: state[:sources], strict: strict }
+          prefetch_vault(value: settings_hash, context: context)
+          state[:sources].each_value { |record| prefetch_vault(value: record[:source], context: context) }
+          publication = lambda do |proposal|
+            publish&.call(proposal)
+            state[:sources] = proposal[:sources]
+          end
+          preparation = lambda do |lease_reader|
+            context[:lease_reader] = lease_reader
+            proposal = { paths: previous[:sources].filter_map { |path, record| path if record[:lease] },
+                         assignments: [], references: [], sources: {}, resolved: 0, unresolved: 0 }
+            walk(settings_hash, path: [], context: context, proposal: proposal)
+            proposal[:paths].uniq!
+            proposal
+          end
 
-        resolved = 0
-        unresolved = 0
-        walk(settings_hash, path: '') do |result|
-          if result == :resolved
-            resolved += 1
-          elsif result == :unresolved
-            unresolved += 1
+          needs_leases = lease_sources?(settings: settings_hash, sources: state[:sources], previous_sources: previous[:sources])
+          proposal = if needs_leases && lease_manager_available?
+                       manager = Legion::Crypt::LeaseManager.instance
+                       unless manager.respond_to?(:update_settings_refs)
+                         raise 'Lease resolution requires legion-crypt >= 1.5.38 for atomic settings reference replacement'
+                       end
+
+                       manager.update_settings_refs(settings: settings_hash, publish: publication, &preparation)
+                     else
+                       apply_resolution(proposal: preparation.call(nil), publish: publication)
+                     end
+          if proposal[:resolved].positive? || proposal[:unresolved].positive?
+            log.info("Settings resolver: #{proposal[:resolved]} resolved, #{proposal[:unresolved]} unresolved")
           end
         end
+        settings_hash
+      end
 
-        log.info("Settings resolver: #{resolved} resolved, #{unresolved} unresolved") if resolved.positive? || unresolved.positive?
+      # Strong state values keep provenance alive across GC; weak owner references
+      # avoid retaining retired loaders and never alter Hash serialization or dup.
+      def resolution_state(owner:)
+        @source_mutex.synchronize do
+          @source_states.delete_if { |_id, state| !state[:owner].weakref_alive? }
+          # Identity keys must not retain owners; compare_by_identity would hold them strongly.
+          @source_states[owner.object_id] ||= { owner: WeakRef.new(owner), mutex: Mutex.new, sources: {} } # rubocop:disable Lint/HashCompareByIdentity
+        end
+      end
 
-        settings_hash
+      def lease_sources?(settings:, sources:, previous_sources:)
+        count_lease_refs(settings).positive? ||
+          sources.any? { |_path, record| count_lease_refs(record[:source]).positive? } ||
+          previous_sources.any? { |_path, record| record[:lease] }
       end
 
-      def resolve_value(value)
+      def resolve_value(value, context: nil)
         case value
         when String
           return value unless value.match?(URI_PATTERN)
 
-          resolve_single(value)
+          resolve_single(value, context: context)
         when Array
           return value unless resolvable_chain?(value)
 
-          resolve_chain(value)
+          resolve_chain(value, context: context)
         else
           value
         end
       end
 
-      def resolve_single(str)
-        if (m = str.match(VAULT_PATTERN))
-          resolve_vault(m[1], m[2])
-        elsif (m = str.match(LEASE_PATTERN))
-          resolve_lease(m[1], m[2])
-        elsif (m = str.match(ENV_PATTERN))
-          ENV.fetch(m[1], nil)
+      def resolve_single(str, context: nil)
+        if (match = str.match(VAULT_PATTERN))
+          resolve_vault(match[1], match[2], context: context)
+        elsif (match = str.match(LEASE_PATTERN))
+          resolve_lease(match[1], match[2], context: context)
+        elsif (match = str.match(ENV_PATTERN))
+          ENV.fetch(match[1], nil)
         else
           str
         end
       end
 
-      def resolve_chain(arr)
+      def resolve_chain(arr, context: nil)
+        context ||= { vault_available: vault_connected?, vault_cache: {} }
         arr.each do |entry|
           result = if entry.is_a?(String) && entry.match?(URI_PATTERN)
-                     resolve_single(entry)
+                     resolve_single(entry, context: context)
                    else
                      entry
                    end
-          return result unless result.nil?
+          next if result.nil?
+
+          yield(entry) if block_given?
+          return result
         end
         nil
       end
@@ -95,98 +133,122 @@ module Legion
 
       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]&.dig(: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:, &)
-        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
+      def walk(container, path:, context:, proposal:)
+        keys = container.is_a?(Hash) ? container.each_key : container.each_index
+        keys.each do |key|
+          current_path = (path + [key]).freeze
+          next if prepare_value(container: container, key: key, path: current_path, context: context, proposal: proposal)
+
+          value = container[key]
+          walk(value, path: current_path, context: context, proposal: proposal) if value.is_a?(Hash) || value.is_a?(Array)
         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? }
+      def source_declaration(value:, record:)
+        if declaration?(value: value)
+          return value.dup.freeze unless value.is_a?(Array)
+
+          value.map { |entry| entry.is_a?(String) ? entry.dup.freeze : entry }.freeze
+        elsif record && value == record[:value]
+          record[:source]
         end
       end
 
-      def handle_string_value(container, key, value, current_path)
-        return unless value.match?(URI_PATTERN)
+      def declaration?(value:)
+        (value.is_a?(String) && value.match?(URI_PATTERN)) ||
+          (value.is_a?(Array) && resolvable_chain?(value) && value.none? { |entry| entry.is_a?(Hash) || entry.is_a?(Array) })
+      end
 
-        resolved = resolve_single(value)
-        if resolved.nil?
-          log.warn("Settings resolver: could not resolve #{current_path} (#{value})")
-          yield(:unresolved) if block_given?
+      def prepare_value(container:, key:, path:, context:, proposal:)
+        record = context[:sources][path]
+        source = source_declaration(value: container[key], record: record)
+        return unless source
+
+        winner = source
+        value = if source.is_a?(Array)
+                  resolve_chain(source, context: context) { |entry| winner = entry }
+                else
+                  resolve_single(source, context: context)
+                end
+        if value.nil?
+          proposal[:unresolved] += 1
+          raise "Settings resolver: could not resolve #{path.inspect}" if context[:strict]
+
+          log.warn("Settings resolver: could not resolve #{path.inspect}")
+          return source unless record && container[key] == record[:value]
         else
-          container[key] = resolved
-          register_lease_ref(value, current_path) if value.match?(LEASE_PATTERN)
-          yield(:resolved) if block_given?
+          lease = winner.is_a?(String) && winner.match(LEASE_PATTERN)
+          record = { source: source, value: value, lease: lease && { name: lease[1], key: lease[2] } }
+          proposal[:assignments] << { container: container, key: key, value: value }
+          proposal[:resolved] += 1
+        end
+        proposal[:sources][path] = record
+        if record[:lease]
+          proposal[:paths] << path
+          proposal[:references] << record[:lease].merge(path: path, binding: record)
         end
+        source
       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, &)
+      def apply_resolution(proposal:, publish:)
+        snapshots = proposal[:assignments].map do |assignment|
+          container = assignment[:container]
+          raise FrozenError, 'Settings resolver: destination is frozen' if container.frozen?
+
+          [container, assignment[:key], container[assignment[:key]]]
         end
+        begin
+          proposal[:assignments].each { |assignment| assignment[:container][assignment[:key]] = assignment[:value] }
+          publish.call(proposal)
+        rescue StandardError
+          snapshots.reverse_each { |container, key, value| container[key] = value }
+          raise
+        end
+        proposal
       end
 
-      def resolve_vault(path, key)
-        log.debug("resolve_vault: path=#{path}, key=#{key}, vault_available=#{@vault_available}")
-        return nil unless @vault_available
-
-        @vault_cache[path] ||= begin
-          log.debug("resolve_vault: calling Legion::Crypt.read(#{path.inspect})")
-          result = Legion::Crypt.read(path)
-          log.debug("resolve_vault: read returned #{result.nil? ? 'nil' : "keys=#{result.keys.inspect}"}")
-          result
-        rescue StandardError => e
-          log.warn("Settings resolver: vault read failed for #{path}: #{e.class}=#{e.message}")
-          nil
+      def prefetch_vault(value:, context:)
+        case value
+        when String
+          match = value.match(VAULT_PATTERN)
+          resolve_vault(match[1], match[2], context: context) if match
+        when Array
+          value.each { |entry| prefetch_vault(value: entry, context: context) }
+        when Hash
+          value.each_value { |entry| prefetch_vault(value: entry, context: context) }
         end
+      end
 
-        data = @vault_cache[path]
-        unless data.is_a?(Hash)
-          log.debug("resolve_vault: data at #{path} is #{data.class}, returning nil")
-          return nil
+      def resolve_vault(path, key, context: nil)
+        context ||= { vault_available: vault_connected?, vault_cache: {} }
+        return nil unless context[:vault_available]
+
+        cache = context[:vault_cache]
+        unless cache.key?(path)
+          cache[path] = begin
+            Legion::Crypt.read(path)
+          rescue StandardError => e
+            log.warn("Settings resolver: vault read failed for #{path}: #{e.class}=#{e.message}")
+            nil
+          end
         end
+        data = cache[path]
+        return nil unless data.is_a?(Hash)
 
-        value = data[key.to_sym] || data[key.to_s]
-        log.debug("resolve_vault: #{path}##{key} = #{value.nil? ? 'nil' : '<present>'}")
-        value
+        data.key?(key.to_sym) ? data[key.to_sym] : data[key.to_s]
       end
 
-      def resolve_lease(name, key)
+      def resolve_lease(name, key, context: nil)
+        return context[:lease_reader].call(name: name, key: key) if context && context[:lease_reader]
         return nil unless lease_manager_available?
 
         Legion::Crypt::LeaseManager.instance.fetch(name, key)
@@ -197,36 +259,10 @@ module Legion
 
       def lease_manager_available?
         defined?(Legion::Crypt::LeaseManager)
-      rescue StandardError => e
-        log.debug("Legion::Settings::Resolver#lease_manager_available? failed: #{e.message}")
-        false
       end
 
       def resolvable_chain?(arr)
-        arr.any? { |v| v.is_a?(String) && v.match?(URI_PATTERN) }
-      end
-
-      def register_lease_ref(value, path_string)
-        return unless lease_manager_available?
-
-        m = value.match(LEASE_PATTERN)
-        return unless m
-
-        path_parts = path_string.split('.').map(&:to_sym)
-        Legion::Crypt::LeaseManager.instance.register_ref(m[1], m[2], path_parts)
-      rescue StandardError => e
-        log.debug("Legion::Settings::Resolver#register_lease_ref failed for #{path_string}: #{e.message}")
-        nil
-      end
-
-      def register_lease_refs_from_chain(arr, path_string)
-        return unless lease_manager_available?
-
-        arr.each do |entry|
-          next unless entry.is_a?(String)
-
-          register_lease_ref(entry, path_string) if entry.match?(LEASE_PATTERN)
-        end
+        arr.any? { |value| value.is_a?(String) && value.match?(URI_PATTERN) }
       end
 
       def count_lease_refs(hash)
@@ -242,6 +278,9 @@ module Legion
         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
+
+      private_class_method :resolution_state, :lease_sources?, :walk, :source_declaration, :declaration?,
+                           :prepare_value, :apply_resolution, :prefetch_vault
     end
   end
 end

data/lib/legion/settings/schema.rb

@@ -181,8 +181,8 @@ module Legion
       def find_similar(key, candidates)
         key_str = key.to_s
         candidates.map(&:to_s).select { |c| levenshtein(key_str, c) <= 2 }
-                              .min_by { |c| levenshtein(key_str, c) }
-                              &.to_sym
+                  .min_by { |c| levenshtein(key_str, c) }
+                  &.to_sym
       end
 
       def levenshtein(str_a, str_b)

data/lib/legion/settings/version.rb

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

data/lib/legion/settings.rb

@@ -115,10 +115,12 @@ module Legion
       #   Legion::Settings.register_library(:transport, Legion::Transport::Settings.default)
       def register_library(key, defaults)
         sym = key.to_sym
-        return if @registered_libraries&.include?(sym)
+        ensure_loader
+        registered = @registered_libraries&.include?(sym)
+        return if registered && @loader.merged_modules.key?(sym)
 
         merge_settings(sym, defaults)
-        (@registered_libraries ||= []) << sym
+        (@registered_libraries ||= []) << sym unless registered
       end
 
       def define_schema(key, overrides)
@@ -190,10 +192,13 @@ module Legion
       end
 
       def resolve_secrets!
-        ensure_loader
-        require 'legion/settings/resolver'
-        Resolver.resolve_secrets!(@loader.to_hash)
-        logger.debug('Secret resolution complete')
+        @reload_mutex ||= Mutex.new
+        @reload_mutex.synchronize do
+          ensure_loader
+          require 'legion/settings/resolver'
+          Resolver.resolve_secrets!(@loader.to_hash, owner: @loader)
+          logger.debug('Secret resolution complete')
+        end
       end
 
       def schema
@@ -216,17 +221,16 @@ module Legion
       # ------------------------------------------------------------------
       def reload!
         @reload_mutex ||= Mutex.new
-        @reload_mutex.synchronize do
+        changes = @reload_mutex.synchronize do
           return {} unless @loader
 
-          old_hash = @loader.to_hash.dup
           files = @loader.loaded_files.dup
 
           # Re-create loader and replay the same files
           new_loader = Legion::Settings::Loader.new
           new_loader.load_env
           new_loader.load_dns_bootstrap
-          files.each { |f| new_loader.load_file(f) if File.exist?(f) }
+          files.each { |file| new_loader.load_file(file, strict: true) if File.exist?(file) }
 
           # Replay module merges so extension defaults are preserved
           if @loader.respond_to?(:merged_modules)
@@ -238,27 +242,28 @@ module Legion
           # Replay project env overrides (.legionio.env)
           load_project_env(loader: new_loader)
 
-          # Re-resolve secrets (vault://, env://, lease://)
-          begin
-            require 'legion/settings/resolver'
-            Resolver.resolve_secrets!(new_loader.to_hash)
-          rescue StandardError => e
-            logger.warn("Settings reload: secret resolution failed: #{e.message}")
+          require 'legion/settings/resolver'
+          changes = nil
+          publication = lambda do |_proposal|
+            changes = diff_settings(@loader.to_hash, new_loader.to_hash)
+            @loader = new_loader
           end
-
-          new_hash = new_loader.to_hash
-          changes = diff_settings(old_hash, new_hash)
+          Resolver.resolve_secrets!(new_loader.to_hash, owner: new_loader, previous_owner: @loader,
+                                    strict: true, publish: publication)
 
           if changes.empty?
             logger.info('Settings reload: no changes detected')
           else
-            @loader = new_loader
             logger.info("Settings reload: #{changes.size} key(s) changed — #{changes.keys.join(', ')}")
-            fire_reload_callbacks(changes)
           end
 
           changes
         end
+        fire_reload_callbacks(changes) unless changes.empty?
+        changes
+      rescue StandardError => e
+        logger.warn("Settings reload failed: #{e.class}: #{e.message}")
+        raise
       end
 
       # Register a SIGHUP handler that triggers reload!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-settings
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.4
 platform: ruby
 authors:
 - Esity