legion-settings 1.3.26 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4d1e8b1f3f0f96ee8db9d11604d914fc253e430827e37f7e30cc244151dc75b
-  data.tar.gz: 1ed13e9f16b97fc33acc72e484671794210ac4750aef5502fc86e685ec2f9324
+  metadata.gz: baf40211abee6a48e5863077ce8e31fa416afbad9f003933e7edcfca4b8a72ba
+  data.tar.gz: f8faf5fb5eadead569c9f222a70c58e5ac11bc923dc281bd587f3f2704125cd0
 SHA512:
-  metadata.gz: 47ab18a67eef8c35d86e52e9deec5716916754e5a84e0faec1ba3bbed4f24e9f4bb5c7749268eee23c96056ce85ef11c47787ac2df06fa5b918365730ddf6926
-  data.tar.gz: c76877c9e9a19f44c33a816a0580c265f721fe6dd0ef486eb06ec377ac6aedd5ae60fe52b4aaf4d8feb59bb18527f6127da40a0611d27718de3be63af5581b97
+  metadata.gz: 7dbe223a77152d41812ec94bd98457db0570dae8bdea879f58b4ec052fca03eed46d1364617d4affb73d4cd7bc0364e6f6074c5a0fe5d8c433776e900d354417
+  data.tar.gz: b362c5d3a541c5afce645b47656ef1a427b65d58500bd5100e14717451dacaa8024823a188fd97f2475cb2ab1e176912c30ed7ba0496f0f512dd79a593228401

data/.gitignore

@@ -9,7 +9,8 @@
 /tmp/
 /legion/.idea/
 /.idea/
+*.gem
 *.key
 # rspec failure tracking
 .rspec_status
-legionio.key
+legionio.key

data/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+# Standard LegionIO pre-commit configuration
+# Install: pre-commit install
+# Manual:  pre-commit run --all-files
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+        exclude: Gemfile\.lock
+      - id: check-merge-conflict
+
+  - repo: local
+    hooks:
+      - id: rubocop
+        name: RuboCop (autofix)
+        entry: scripts/pre-commit-rubocop.sh
+        language: script
+        types: [ruby]
+        pass_filenames: true
+
+      - id: ruby-syntax
+        name: Ruby syntax check
+        entry: ruby -c
+        language: system
+        types: [ruby]
+        pass_filenames: true

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # 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
+- `Settings.reload!` — re-reads all previously loaded config files and re-resolves vault://, env://, and lease:// references; returns a hash of changed keys with old/new values; thread-safe via internal mutex
+- `Settings.watch!` — registers a SIGHUP handler that triggers `reload!` in a background thread; optionally accepts a block for change notification
+- `Settings.on_reload(&block)` — register callbacks invoked after `reload!` detects changes; multiple callbacks supported, called in order, rescue-safe
+- Private `diff_settings` helper for deep comparison of old vs new config hashes
+- Private `fire_reload_callbacks` for executing registered change callbacks
+
+### Fixed
+- `reload!` preserves programmatic module merges and reapplies `.legionio.env` overrides to the reloaded settings loader
+- `watch!` no-ops when SIGHUP is unavailable and coalesces repeated SIGHUP events through a single reload worker
+- Replaced deprecated helper logging method calls with direct `log.debug/info/warn/error` usage
+
 ## [1.3.26] - 2026-04-02
 
 ### Changed

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.26
+**Version**: 1.3.27
 
 ## Installation
 
@@ -44,6 +44,51 @@ If a caller wants the canonical Legion search directories, use `Legion::Settings
 
 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.
 
+### Hot Reload
+
+`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.
+
+```ruby
+changes = Legion::Settings.reload!
+
+changes
+# {
+#   "llm.default_model" => { old: "old-model", new: "new-model" }
+# }
+```
+
+Callbacks run only when changes are detected:
+
+```ruby
+Legion::Settings.on_reload do |changes|
+  Legion::Settings.logger.info("Settings changed: #{changes.keys.join(', ')}")
+end
+```
+
+`watch!` installs a SIGHUP handler when the platform supports it. Repeated signals are coalesced through one background reload worker, so rapid SIGHUP bursts do not create unbounded reload threads.
+
+```ruby
+Legion::Settings.watch! do |changes|
+  Legion::Settings.logger.info("Reloaded #{changes.size} setting(s)")
+end
+
+# Later, from a shell:
+# kill -HUP <daemon_pid>
+```
+
+On platforms without `HUP`, `watch!` logs and returns without raising. Direct `reload!` remains available for API endpoints, tests, or environments that use a different process-control mechanism.
+
+### Project Environment Overrides
+
+When present, the nearest `.legionio.env` file is loaded after base settings and module defaults. Dot notation maps to nested settings:
+
+```dotenv
+llm.default_model=claude-sonnet
+cache.driver=redis
+```
+
+Hot reload picks up changes to this file as part of the same `reload!` flow.
+
 ### Secret Resolution
 
 Settings values can reference external secret sources using URI syntax. Three schemes are supported:

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/agent_loader.rb

@@ -20,7 +20,7 @@ module Legion
             definition = load_file(path)
             next unless definition && valid?(definition)
 
-            log_debug("Agent loaded: #{definition[:name]} (#{path})")
+            log.debug("Agent loaded: #{definition[:name]} (#{path})")
             definition.merge(_source_path: path, _source_mtime: File.mtime(path))
           end
         end
@@ -32,7 +32,7 @@ module Legion
           when '.json'         then ::JSON.parse(content, symbolize_names: true)
           end
         rescue StandardError => e
-          log_warn("Failed to parse agent file #{path}: #{e.message}")
+          log.warn("Failed to parse agent file #{path}: #{e.message}")
           nil
         end
 
@@ -51,14 +51,6 @@ 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
-
-        def log_debug(message)
-          log.debug(message)
-        end
-
-        def log_warn(message)
-          log.warn(message)
-        end
       end
     end
   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