stroma 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27a735955a54fe9ea248a066afbdf10edaa55bc903b83574e84d405fb01fa020
-  data.tar.gz: e63528c3ac53e3a32a757493745dac02ee46958a486b184cda3d3d4fc4463c6f
+  metadata.gz: 3651f535308d76dc210bfb0d49b87179e20ea806e4bb8032eee5165c7f23d635
+  data.tar.gz: 5083f7bc1e8541832be170ee35eb9ddf4852b5fd90e76af8c6d7303066e2a927
 SHA512:
-  metadata.gz: 19f5d6847f269dfe65070f267426b68ec7a61b72cdfde478ec3542ed9d75a232465c32412eab4bb8d432e4fb648962b309a5d7dc450ec2b14ce329506a86e55c
-  data.tar.gz: fc4c1300028fa543f2d097d70dcba472644837579a73d58235e51215ac7792d1ce0a1e423f3daac97dac1bcbcad0ab48642f3b63ae663dade353e505bd59466d
+  metadata.gz: 2b56c004b08152484972a38b47919c5b1b299d9316bbbcebc2c533190ea766dee62a9882d81ca97281874c4d47bf8e4447fa31142bd51d9329d2c8a17fe9c0da
+  data.tar.gz: cee73e3a9040cf6da488c3326333618d30128dc448179e9d184b991d8602ea7da3ebfcbd50eab9e1d6559b5b14214aaed90f42ad1a6e3757d435933ba3f4f12b

data/README.md

@@ -1,4 +1,12 @@
-<h1 align="center">Stroma</h1>
+<p align="center">
+  <a href="https://servactory.com" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/servactory/stroma/main/.github/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/servactory/stroma/main/.github/logo-light.svg">
+      <img alt="Stroma" src="https://raw.githubusercontent.com/servactory/stroma/main/.github/logo-light.svg" width="350" height="70" style="max-width: 100%;">
+    </picture>
+  </a>
+</p>
 
 <p align="center">
   A foundation for building modular, extensible DSLs in Ruby.
@@ -39,32 +47,27 @@ Building modular DSLs shouldn't require reinventing the wheel. Stroma provides a
 Stroma is a foundation for library authors building DSL-driven frameworks (service objects, form objects, decorators, etc.).
 
 **Core lifecycle:**
-1. **Register** - Define DSL modules at boot time via `Stroma::Registry`
-2. **Compose** - Classes include `Stroma::DSL` to gain all registered modules automatically
-3. **Extend** (optional) - Users can add cross-cutting logic via `before`/`after` hooks
+1. **Define** - Create a Matrix with DSL modules at boot time
+2. **Include** - Classes include the matrix's DSL to gain all modules
+3. **Extend** (optional) - Add cross-cutting logic via `before`/`after` hooks
 
 ## 🚀 Quick Start
 
 ### Installation
 
 ```ruby
-spec.add_dependency "stroma", ">= 0.3"
+spec.add_dependency "stroma", ">= 0.4"
 ```
 
 ### Define your library's DSL
 
 ```ruby
 module MyLib
-  module DSL
-    # Register DSL modules at load time
-    Stroma::Registry.register(:inputs, MyLib::Inputs::DSL)
-    Stroma::Registry.register(:actions, MyLib::Actions::DSL)
-    Stroma::Registry.finalize!
-
-    def self.included(base)
-      base.include(Stroma::DSL)
-    end
+  STROMA = Stroma::Matrix.define(:my_lib) do
+    register :inputs, MyLib::Inputs::DSL
+    register :actions, MyLib::Actions::DSL
   end
+  private_constant :STROMA
 end
 ```
 
@@ -73,15 +76,31 @@ end
 ```ruby
 module MyLib
   class Base
-    include MyLib::DSL
+    include STROMA.dsl
   end
 end
 ```
 
 ### Usage
 
+Create an intermediate class with lifecycle hooks:
+
 ```ruby
-class UserService < MyLib::Base
+class ApplicationService < MyLib::Base
+  # Add lifecycle hooks (optional)
+  extensions do
+    before :actions, ApplicationService::Extensions::Rollbackable::DSL
+  end
+end
+```
+
+Build services that inherit extension functionality:
+
+```ruby
+class UserService < ApplicationService
+  # DSL method from Rollbackable extension
+  on_rollback(...)
+
   input :email, type: String
 
   make :create_user
@@ -94,6 +113,12 @@ class UserService < MyLib::Base
 end
 ```
 
+Extensions allow you to add cross-cutting concerns like transactions, authorization, and rollback support. See [extension examples](https://github.com/servactory/servactory/tree/main/examples/application_service/extensions) for implementation details.
+
+## 💎 Projects Using Stroma
+
+- [Servactory](https://github.com/servactory/servactory) — Service objects framework for Ruby applications
+
 ## 🤝 Contributing
 
 We welcome contributions! Check out our [Contributing Guide](https://github.com/servactory/stroma/blob/main/CONTRIBUTING.md) to get started.

data/lib/stroma/dsl/generator.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Stroma
+  module DSL
+    # Generates a DSL module scoped to a specific Matrix.
+    #
+    # ## Purpose
+    #
+    # Creates a module that:
+    # - Stores matrix reference on the module itself
+    # - Defines ClassMethods for service classes
+    # - Handles inheritance with state duplication
+    #
+    # Memory model:
+    # - Matrix owns @dsl_module (generated once, cached)
+    # - ServiceClass gets @stroma_matrix (same reference)
+    # - ServiceClass gets @stroma (unique State per class)
+    #
+    # ## Deferred Entry Inclusion
+    #
+    # Entry extensions are NOT included via `Module#include` at the base class level.
+    # Instead, only the `self.included` callback is fired (via `send(:included, base)`)
+    # to set up ClassMethods, constants, etc. The actual module insertion into the
+    # ancestor chain (`append_features`) is deferred until {Hooks::Applier} interleaves
+    # entries with hooks in child classes.
+    #
+    # **Contract:** Entry extensions MUST implement `self.included` as idempotent.
+    # The callback fires twice per entry per class hierarchy:
+    # 1. At base class creation (deferred, via `send(:included, base)`)
+    # 2. At child class creation (real, via `include` in {Hooks::Applier})
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # # Called internally by Matrix#dsl
+    # dsl_module = Stroma::DSL::Generator.call(matrix)
+    #
+    # # The generated module is included in base classes
+    # class MyLib::Base
+    #   include dsl_module
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Called by Matrix#dsl to generate the DSL module.
+    # Generated module includes all registered extensions.
+    class Generator
+      class << self
+        # Generates a DSL module for the given matrix.
+        #
+        # @param matrix [Matrix] The matrix to generate DSL for
+        # @return [Module] The generated DSL module
+        def call(matrix)
+          new(matrix).generate
+        end
+      end
+
+      # Creates a new generator for the given matrix.
+      #
+      # @param matrix [Matrix] The matrix to generate DSL for
+      def initialize(matrix)
+        @matrix = matrix
+      end
+
+      # Generates the DSL module.
+      #
+      # Creates a module with ClassMethods that provides:
+      # - stroma_matrix accessor for matrix reference
+      # - stroma accessor for per-class state
+      # - inherited hook for state duplication
+      # - extensions DSL for registering hooks
+      #
+      # @return [Module] The generated DSL module
+      def generate # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        matrix = @matrix
+        class_methods = build_class_methods
+
+        mod = Module.new do
+          @stroma_matrix = matrix
+
+          class << self
+            attr_reader :stroma_matrix
+
+            def included(base)
+              mtx = stroma_matrix
+              base.extend(self::ClassMethods)
+              base.instance_variable_set(:@stroma_matrix, mtx)
+              base.instance_variable_set(:@stroma, State.new)
+
+              # Deferred inclusion: triggers `included` callback without `append_features`.
+              # The callback runs ClassMethods/Workspace setup on base.
+              # `append_features` (actual module insertion into ancestors) is deferred
+              # until Applier interleaves entries with hooks in child classes.
+              # NOTE: `included` will fire again when Applier calls `include` on child,
+              # so entry extensions must design `self.included` as idempotent.
+              mtx.entries.each { |entry| entry.extension.send(:included, base) }
+            end
+          end
+
+          const_set(:ClassMethods, class_methods)
+        end
+
+        Utils.name_module(mod, "Stroma::DSL(#{matrix.name})")
+        Utils.name_module(class_methods, "Stroma::DSL(#{matrix.name})::ClassMethods")
+
+        mod
+      end
+
+      private
+
+      # Builds the ClassMethods module.
+      #
+      # @return [Module] The ClassMethods module
+      def build_class_methods # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        Module.new do
+          attr_reader :stroma_matrix
+
+          def stroma
+            @stroma ||= State.new
+          end
+
+          def inherited(child)
+            super
+            child.instance_variable_set(:@stroma_matrix, stroma_matrix)
+            child.instance_variable_set(:@stroma, stroma.dup)
+            Hooks::Applier.apply!(child, child.stroma.hooks, stroma_matrix)
+          end
+
+          private
+
+          def extensions(&block)
+            @stroma_hooks_factory ||= Hooks::Factory.new(stroma.hooks, stroma_matrix)
+            @stroma_hooks_factory.instance_eval(&block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stroma/hooks/applier.rb

@@ -2,58 +2,109 @@
 
 module Stroma
   module Hooks
-    # Applies registered hooks to a target class.
+    # Applies registered hooks to a target class with deferred entry inclusion.
     #
     # ## Purpose
     #
-    # Iterates through all registered DSL modules and includes corresponding
-    # before/after hooks in the target class. For each registry entry,
-    # before hooks are included first, then after hooks.
+    # Manages hook and entry module inclusion into the target class.
+    # Operates in three modes depending on current state:
+    # - No hooks: returns immediately (entries stay deferred)
+    # - Entries already in ancestors: includes only new hooks
+    # - Entries not in ancestors: interleaves entries with hooks for correct MRO
     #
     # ## Usage
     #
     # ```ruby
-    # applier = Stroma::Hooks::Applier.new(ChildService, hooks)
+    # # Called internally during class inheritance
+    # applier = Stroma::Hooks::Applier.new(ChildService, hooks, matrix)
     # applier.apply!
-    # # ChildService now includes all hook modules
     # ```
     #
     # ## Integration
     #
-    # Called by Stroma::DSL.inherited after duplicating
-    # parent's configuration. Uses Registry.entries to determine
-    # hook application order.
+    # Called by DSL::Generator's inherited hook.
+    # Creates a temporary instance that is garbage collected after apply!.
     class Applier
+      class << self
+        # Applies all registered hooks to the target class.
+        #
+        # Convenience class method that creates an applier and applies hooks.
+        #
+        # @param target_class [Class] The class to apply hooks to
+        # @param hooks [Collection] The hooks collection to apply
+        # @param matrix [Matrix] The matrix providing registry entries
+        # @return [void]
+        def apply!(target_class, hooks, matrix)
+          new(target_class, hooks, matrix).apply!
+        end
+      end
+
       # Creates a new applier for applying hooks to a class.
       #
       # @param target_class [Class] The class to apply hooks to
       # @param hooks [Collection] The hooks collection to apply
-      def initialize(target_class, hooks)
+      # @param matrix [Matrix] The matrix providing registry entries
+      def initialize(target_class, hooks, matrix)
         @target_class = target_class
         @hooks = hooks
+        @matrix = matrix
       end
 
       # Applies all registered hooks to the target class.
       #
-      # For each registry entry, includes before hooks first,
-      # then after hooks. Does nothing if hooks collection is empty.
+      # Three modes based on current state:
+      # - No hooks: return immediately (defer entry inclusion)
+      # - Entries already in ancestors: include only hooks
+      # - Entries not in ancestors: interleave entries with hooks
       #
       # @return [void]
-      #
-      # @example
-      #   applier.apply!
-      #   # Target class now includes all extension modules
       def apply!
         return if @hooks.empty?
 
-        Registry.entries.each do |entry|
-          @hooks.before(entry.key).each do |hook|
-            @target_class.include(hook.extension)
-          end
+        if entries_in_ancestors?
+          include_hooks_only
+        else
+          include_entries_with_hooks
+        end
+      end
+
+      private
+
+      # Checks whether all entry extensions are already in the target class ancestors.
+      #
+      # Uses all? so that partial inclusion (some entries present, some not)
+      # falls through to include_entries_with_hooks where Ruby skips
+      # already-included modules (idempotent) and interleaves the rest.
+      #
+      # @return [Boolean]
+      def entries_in_ancestors?
+        ancestors = @target_class.ancestors
+        @matrix.entries.all? { |e| ancestors.include?(e.extension) }
+      end
+
+      # Includes entries interleaved with their hooks.
+      #
+      # For each entry: after hooks first (reversed), then entry, then before hooks (reversed).
+      # reverse_each ensures first registered = outermost in MRO.
+      #
+      # @return [void]
+      def include_entries_with_hooks
+        @matrix.entries.each do |entry|
+          @hooks.after(entry.key).reverse_each { |hook| @target_class.include(hook.extension) }
+          @target_class.include(entry.extension)
+          @hooks.before(entry.key).reverse_each { |hook| @target_class.include(hook.extension) }
+        end
+      end
 
-          @hooks.after(entry.key).each do |hook|
-            @target_class.include(hook.extension)
-          end
+      # Includes only hook extensions without entries.
+      #
+      # Used when entries are already in ancestors (multi-level inheritance).
+      #
+      # @return [void]
+      def include_hooks_only
+        @matrix.entries.each do |entry|
+          @hooks.before(entry.key).reverse_each { |hook| @target_class.include(hook.extension) }
+          @hooks.after(entry.key).reverse_each { |hook| @target_class.include(hook.extension) }
         end
       end
     end

data/lib/stroma/hooks/collection.rb

@@ -59,7 +59,7 @@ module Stroma
       # @return [void]
       def initialize_dup(original)
         super
-        @collection = original.instance_variable_get(:@collection).dup
+        @collection = original.collection.dup
       end
 
       # Adds a new hook to the collection.
@@ -96,6 +96,10 @@ module Stroma
       def after(key)
         @collection.select { |hook| hook.after? && hook.target_key == key }
       end
+
+      protected
+
+      attr_reader :collection
     end
   end
 end

data/lib/stroma/hooks/factory.rb

@@ -6,21 +6,16 @@ module Stroma
     #
     # ## Purpose
     #
-    # Provides the `before` and `after` methods used within the extensions
-    # block to register hooks. Validates that target keys exist in Registry
-    # before adding hooks.
+    # Provides before/after DSL methods for hook registration.
+    # Validates target keys against the matrix's registry.
+    # Delegates to Hooks::Collection for storage.
     #
     # ## Usage
     #
-    # Used within `extensions` block in classes that include Stroma::DSL:
-    #
     # ```ruby
-    # # Library Base class (includes Stroma::DSL via library's DSL module)
-    # class MyLib::Base
-    #   include MyLib::DSL  # MyLib::DSL includes Stroma::DSL
-    #
+    # class MyService < MyLib::Base
     #   extensions do
-    #     before :actions, ValidationModule
+    #     before :actions, ValidationModule, AuthModule
     #     after :outputs, LoggingModule
     #   end
     # end
@@ -28,15 +23,16 @@ module Stroma
     #
     # ## Integration
     #
-    # Created by DSL.extensions method and receives instance_eval of the block.
-    # Validates keys against Registry.keys and raises UnknownHookTarget
-    # for invalid keys.
+    # Created by DSL::Generator's extensions method.
+    # Cached as @stroma_hooks_factory on each service class.
     class Factory
       # Creates a new factory for registering hooks.
       #
       # @param hooks [Collection] The hooks collection to add to
-      def initialize(hooks)
+      # @param matrix [Matrix] The matrix providing valid keys
+      def initialize(hooks, matrix)
         @hooks = hooks
+        @matrix = matrix
       end
 
       # Registers one or more before hooks for a target key.
@@ -44,6 +40,7 @@ module Stroma
       # @param key [Symbol] The registry key to hook before
       # @param extensions [Array<Module>] Extension modules to include
       # @raise [Exceptions::UnknownHookTarget] If key is not registered
+      # @return [void]
       #
       # @example
       #   before :actions, ValidationModule, AuthorizationModule
@@ -57,6 +54,7 @@ module Stroma
       # @param key [Symbol] The registry key to hook after
       # @param extensions [Array<Module>] Extension modules to include
       # @raise [Exceptions::UnknownHookTarget] If key is not registered
+      # @return [void]
       #
       # @example
       #   after :outputs, LoggingModule, AuditModule
@@ -67,16 +65,17 @@ module Stroma
 
       private
 
-      # Validates that the key exists in the Registry.
+      # Validates that the key exists in the matrix's registry.
       #
       # @param key [Symbol] The key to validate
       # @raise [Exceptions::UnknownHookTarget] If key is not registered
+      # @return [void]
       def validate_key!(key)
-        return if Registry.key?(key)
+        return if @matrix.key?(key)
 
         raise Exceptions::UnknownHookTarget,
-              "Unknown hook target: #{key.inspect}. " \
-              "Valid keys: #{Registry.keys.map(&:inspect).join(', ')}"
+              "Unknown hook target #{key.inspect} for #{@matrix.name.inspect}. " \
+              "Valid: #{@matrix.keys.map(&:inspect).join(', ')}"
       end
     end
   end

data/lib/stroma/hooks/hook.rb

@@ -46,7 +46,7 @@ module Stroma
       # @param extension [Module] Extension module to include
       # @raise [Exceptions::InvalidHookType] If type is invalid
       def initialize(type:, target_key:, extension:)
-        if VALID_HOOK_TYPES.exclude?(type)
+        unless VALID_HOOK_TYPES.include?(type)
           raise Exceptions::InvalidHookType,
                 "Invalid hook type: #{type.inspect}. Valid types: #{VALID_HOOK_TYPES.map(&:inspect).join(', ')}"
         end

data/lib/stroma/matrix.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Stroma
+  # Main entry point for libraries using Stroma.
+  #
+  # ## Purpose
+  #
+  # Creates an isolated registry and generates a scoped DSL module.
+  # Each matrix has its own registry - no conflicts with other libraries.
+  #
+  # Lifecycle:
+  # - Boot time: Matrix.define creates Registry, registers extensions
+  # - Boot time: finalize! freezes registry, dsl generates Module
+  # - Boot time: freeze makes Matrix immutable
+  # - Runtime: All structures frozen, no allocations
+  #
+  # ## Usage
+  #
+  # ```ruby
+  # module MyLib
+  #   STROMA = Stroma::Matrix.define(:my_lib) do
+  #     register :inputs, Inputs::DSL
+  #     register :outputs, Outputs::DSL
+  #   end
+  #   private_constant :STROMA
+  # end
+  #
+  # class MyLib::Base
+  #   include MyLib::STROMA.dsl
+  # end
+  # ```
+  #
+  # ## Integration
+  #
+  # Stored as a constant in the library's namespace.
+  # Owns the Registry and generates DSL module via DSL::Generator.
+  class Matrix
+    class << self
+      # Defines a new Matrix with given name.
+      #
+      # Preferred way to create a Matrix. Semantically indicates
+      # that we are defining an immutable DSL scope.
+      #
+      # @param name [Symbol, String] The matrix identifier
+      # @yield Block for registering DSL modules
+      # @return [Matrix] The frozen matrix instance
+      #
+      # @example
+      #   STROMA = Stroma::Matrix.define(:my_lib) do
+      #     register :inputs, Inputs::DSL
+      #     register :outputs, Outputs::DSL
+      #   end
+      def define(name, &block)
+        new(name, &block)
+      end
+    end
+
+    # @!attribute [r] name
+    #   @return [Symbol] The matrix identifier
+    # @!attribute [r] registry
+    #   @return [Registry] The registry of DSL modules
+    # @!attribute [r] dsl
+    #   @return [Module] The DSL module to include in base classes
+    attr_reader :name, :registry, :dsl
+
+    # Creates a new Matrix with given name.
+    #
+    # Evaluates the block to register DSL modules, then finalizes
+    # the registry and freezes the matrix.
+    #
+    # @param name [Symbol, String] The matrix identifier
+    # @yield Block for registering DSL modules
+    def initialize(name, &block)
+      @name = name.to_sym
+      @registry = Registry.new(@name)
+
+      instance_eval(&block) if block_given?
+      @registry.finalize!
+      @dsl = DSL::Generator.call(self)
+      freeze
+    end
+
+    # Registers a DSL module with the given key.
+    #
+    # @param key [Symbol] The registry key
+    # @param extension [Module] The DSL module to register
+    # @return [void]
+    def register(key, extension)
+      @registry.register(key, extension)
+    end
+
+    # Returns all registered entries.
+    #
+    # @return [Array<Entry>] The registry entries
+    def entries
+      registry.entries
+    end
+
+    # Returns all registered keys.
+    #
+    # @return [Array<Symbol>] The registry keys
+    def keys
+      registry.keys
+    end
+
+    # Checks if a key is registered.
+    #
+    # @param key [Symbol] The key to check
+    # @return [Boolean] true if the key is registered
+    def key?(key)
+      registry.key?(key)
+    end
+  end
+end

data/lib/stroma/registry.rb

@@ -1,92 +1,118 @@
 # frozen_string_literal: true
 
 module Stroma
-  # Manages global registration of DSL modules for Stroma.
+  # Manages registration of DSL modules for a specific matrix.
   #
   # ## Purpose
   #
-  # Singleton registry that stores all DSL modules that will be included
-  # in service classes. Implements two-phase lifecycle: registration
-  # followed by finalization.
+  # Stores DSL module entries with their keys.
+  # Implements two-phase lifecycle: registration → finalization.
+  # Each Matrix has its own Registry - no global state.
   #
   # ## Usage
   #
   # ```ruby
-  # # During gem initialization:
-  # Stroma::Registry.register(:inputs, Inputs::DSL)
-  # Stroma::Registry.register(:outputs, Outputs::DSL)
-  # Stroma::Registry.finalize!
+  # registry = Stroma::Registry.new(:my_lib)
+  # registry.register(:inputs, Inputs::DSL)
+  # registry.register(:outputs, Outputs::DSL)
+  # registry.finalize!
   #
-  # # After finalization:
-  # Stroma::Registry.keys       # => [:inputs, :outputs]
-  # Stroma::Registry.key?(:inputs)  # => true
+  # registry.keys      # => [:inputs, :outputs]
+  # registry.key?(:inputs)  # => true
   # ```
   #
   # ## Integration
   #
-  # Used by Stroma::DSL to include all registered modules in service classes.
-  # Used by Stroma::Hooks::Factory to validate hook target keys.
-  #
-  # ## Thread Safety
-  #
-  # Registration must occur during single-threaded boot phase.
-  # After finalization, all read operations are thread-safe.
+  # Created and owned by Matrix.
+  # Entries are accessed via Matrix#entries and Matrix#keys.
   class Registry
-    include Singleton
+    # @!attribute [r] matrix_name
+    #   @return [Symbol] The name of the owning matrix
+    attr_reader :matrix_name
 
-    class << self
-      delegate :register,
-               :finalize!,
-               :entries,
-               :keys,
-               :key?,
-               to: :instance
-    end
-
-    def initialize
+    # Creates a new registry for the given matrix.
+    #
+    # @param matrix_name [Symbol, String] The matrix identifier
+    def initialize(matrix_name)
+      @matrix_name = matrix_name.to_sym
       @entries = []
       @finalized = false
     end
 
+    # Registers a DSL module with the given key.
+    #
+    # @param key [Symbol, String] The registry key
+    # @param extension [Module] The DSL module to register
+    # @raise [Exceptions::RegistryFrozen] If registry is finalized
+    # @raise [Exceptions::KeyAlreadyRegistered] If key already exists
+    # @return [void]
     def register(key, extension)
-      raise Exceptions::RegistryFrozen, "Registry is finalized" if @finalized
+      if @finalized
+        raise Exceptions::RegistryFrozen,
+              "Registry for #{@matrix_name.inspect} is finalized"
+      end
 
+      key = key.to_sym
       if @entries.any? { |e| e.key == key }
-        raise Exceptions::KeyAlreadyRegistered, "Key #{key.inspect} already registered"
+        raise Exceptions::KeyAlreadyRegistered,
+              "Key #{key.inspect} already registered in #{@matrix_name.inspect}"
       end
 
       @entries << Entry.new(key:, extension:)
     end
 
+    # Finalizes the registry, preventing further registrations.
+    #
+    # Idempotent - can be called multiple times safely.
+    #
+    # @return [void]
     def finalize!
       return if @finalized
 
       @entries.freeze
+      @keys = @entries.map(&:key).freeze
       @finalized = true
     end
 
+    # Returns all registered entries.
+    #
+    # @raise [Exceptions::RegistryNotFinalized] If not finalized
+    # @return [Array<Entry>] The registry entries
     def entries
       ensure_finalized!
       @entries
     end
 
+    # Returns all registered keys.
+    #
+    # @raise [Exceptions::RegistryNotFinalized] If not finalized
+    # @return [Array<Symbol>] The registry keys
     def keys
       ensure_finalized!
-      @entries.map(&:key)
+      @keys
     end
 
+    # Checks if a key is registered.
+    #
+    # @param key [Symbol, String] The key to check
+    # @raise [Exceptions::RegistryNotFinalized] If not finalized
+    # @return [Boolean] true if the key is registered
     def key?(key)
       ensure_finalized!
-      @entries.any? { |e| e.key == key }
+      @keys.include?(key.to_sym)
     end
 
     private
 
+    # Ensures the registry is finalized.
+    #
+    # @raise [Exceptions::RegistryNotFinalized] If not finalized
+    # @return [void]
     def ensure_finalized!
       return if @finalized
 
       raise Exceptions::RegistryNotFinalized,
-            "Registry not finalized. Call Stroma::Registry.finalize! after registration."
+            "Registry for #{@matrix_name.inspect} not finalized"
     end
   end
 end

data/lib/stroma/settings/collection.rb

@@ -61,7 +61,7 @@ module Stroma
       # @return [void]
       def initialize_dup(original)
         super
-        @storage = original.instance_variable_get(:@storage).transform_values(&:dup)
+        @storage = original.storage.transform_values(&:dup)
       end
 
       # Accesses or creates RegistrySettings for a registry key.
@@ -83,6 +83,10 @@ module Stroma
       def to_h
         @storage.transform_values(&:to_h)
       end
+
+      protected
+
+      attr_reader :storage
     end
   end
 end

data/lib/stroma/settings/registry_settings.rb

@@ -59,7 +59,7 @@ module Stroma
       # @return [void]
       def initialize_dup(original)
         super
-        @storage = original.instance_variable_get(:@storage).transform_values(&:dup)
+        @storage = original.storage.transform_values(&:dup)
       end
 
       # Accesses or creates a Setting for an extension.
@@ -81,6 +81,10 @@ module Stroma
       def to_h
         @storage.transform_values(&:to_h)
       end
+
+      protected
+
+      attr_reader :storage
     end
   end
 end

data/lib/stroma/settings/setting.rb

@@ -69,7 +69,7 @@ module Stroma
       # @return [void]
       def initialize_dup(original)
         super
-        @data = deep_dup(original.instance_variable_get(:@data))
+        @data = deep_dup(original.data)
       end
 
       # Converts to a plain Hash.
@@ -93,6 +93,10 @@ module Stroma
         @data.fetch(key.to_sym, *args, &block)
       end
 
+      protected
+
+      attr_reader :data
+
       private
 
       # Recursively duplicates nested Hash and Array structures.

data/lib/stroma/state.rb

@@ -60,8 +60,8 @@ module Stroma
     # @return [void]
     def initialize_dup(original)
       super
-      @hooks = original.instance_variable_get(:@hooks).dup
-      @settings = original.instance_variable_get(:@settings).dup
+      @hooks = original.hooks.dup
+      @settings = original.settings.dup
     end
   end
 end

data/lib/stroma/utils.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Stroma
+  # Shared utility methods for the Stroma framework.
+  #
+  # ## Purpose
+  #
+  # Provides common helper methods used across multiple Stroma components.
+  # All methods are module functions - callable as both module methods
+  # and instance methods when included.
+  module Utils
+    module_function
+
+    # Assigns a temporary name to an anonymous module for debugging clarity.
+    # Uses set_temporary_name (Ruby 3.3+) when available.
+    #
+    # TODO: Remove the else branch when Ruby 3.2 support is dropped.
+    #       The define_singleton_method fallback is a temporary workaround
+    #       that only affects #inspect and #to_s. Unlike set_temporary_name,
+    #       it does not set #name, so the module remains technically anonymous.
+    #
+    # @param mod [Module] The module to name
+    # @param name [String] The temporary name
+    # @return [void]
+    def name_module(mod, name)
+      if mod.respond_to?(:set_temporary_name)
+        mod.set_temporary_name(name)
+      else
+        mod.define_singleton_method(:inspect) { name }
+        mod.define_singleton_method(:to_s) { name }
+      end
+    end
+  end
+end

data/lib/stroma/version.rb

@@ -3,7 +3,7 @@
 module Stroma
   module VERSION
     MAJOR = 0
-    MINOR = 3
+    MINOR = 5
     PATCH = 0
     PRE = nil
 

data/lib/stroma.rb

@@ -2,8 +2,6 @@
 
 require "zeitwerk"
 
-require "active_support/all"
-
 loader = Zeitwerk::Loader.for_gem
 loader.ignore("#{__dir__}/stroma/test_kit/rspec")
 loader.inflector.inflect(

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stroma
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.1'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -132,7 +118,7 @@ files:
 - README.md
 - Rakefile
 - lib/stroma.rb
-- lib/stroma/dsl.rb
+- lib/stroma/dsl/generator.rb
 - lib/stroma/engine.rb
 - lib/stroma/entry.rb
 - lib/stroma/exceptions/base.rb
@@ -145,11 +131,13 @@ files:
 - lib/stroma/hooks/collection.rb
 - lib/stroma/hooks/factory.rb
 - lib/stroma/hooks/hook.rb
+- lib/stroma/matrix.rb
 - lib/stroma/registry.rb
 - lib/stroma/settings/collection.rb
 - lib/stroma/settings/registry_settings.rb
 - lib/stroma/settings/setting.rb
 - lib/stroma/state.rb
+- lib/stroma/utils.rb
 - lib/stroma/version.rb
 homepage: https://github.com/servactory/stroma
 licenses:
@@ -173,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Foundation for building modular, extensible DSLs
 test_files: []

data/lib/stroma/dsl.rb

@@ -1,124 +0,0 @@
-# frozen_string_literal: true
-
-module Stroma
-  # Main integration point between Stroma and service classes.
-  #
-  # ## Purpose
-  #
-  # Module that provides the core Stroma functionality to service classes:
-  # - Includes all registered DSL modules
-  # - Provides extensions block for hook registration
-  # - Handles inheritance with proper state copying
-  #
-  # ## Usage
-  #
-  # Library authors create a DSL module that includes Stroma::DSL:
-  #
-  # ```ruby
-  # module MyLib::DSL
-  #   def self.included(base)
-  #     base.include(Stroma::DSL)
-  #   end
-  # end
-  #
-  # class MyLib::Base
-  #   include MyLib::DSL
-  #
-  #   extensions do
-  #     before :actions, MyExtension
-  #   end
-  # end
-  # ```
-  #
-  # ## Extension Settings Access
-  #
-  # Extensions access their settings through the stroma.settings hierarchy:
-  #
-  # ```ruby
-  # # In ClassMethods:
-  # stroma.settings[:actions][:authorization][:method_name] = :authorize
-  #
-  # # In InstanceMethods:
-  # self.class.stroma.settings[:actions][:authorization][:method_name]
-  # ```
-  #
-  # ## Integration
-  #
-  # Included by service classes that want Stroma hook functionality.
-  # Provides ClassMethods with: stroma, inherited, extensions.
-  module DSL
-    def self.included(base)
-      base.extend(ClassMethods)
-
-      Registry.entries.each do |entry|
-        base.include(entry.extension)
-      end
-    end
-
-    # Class-level methods for Stroma integration.
-    #
-    # ## Purpose
-    #
-    # Provides access to Stroma state and hooks DSL at the class level.
-    # Handles proper duplication during inheritance.
-    #
-    # ## Key Methods
-    #
-    # - `stroma` - Access the State container
-    # - `inherited` - Copy state to child classes
-    # - `extensions` - DSL block for hook registration
-    module ClassMethods
-      def self.extended(base)
-        base.instance_variable_set(:@stroma, State.new)
-      end
-
-      # Handles inheritance by duplicating Stroma state.
-      #
-      # Creates an independent copy of hooks and settings for the child class,
-      # then applies all registered hooks to the child.
-      #
-      # @param child [Class] The child class being created
-      # @return [void]
-      def inherited(child)
-        super
-
-        child.instance_variable_set(:@stroma, stroma.dup)
-
-        Hooks::Applier.new(child, child.stroma.hooks).apply!
-      end
-
-      # Returns the Stroma state for this service class.
-      #
-      # @return [State] The Stroma state container
-      #
-      # @example Accessing hooks
-      #   stroma.hooks.before(:actions)
-      #
-      # @example Accessing settings
-      #   stroma.settings[:actions][:authorization][:method_name]
-      def stroma
-        @stroma ||= State.new
-      end
-
-      private
-
-      # DSL block for registering hooks.
-      #
-      # Evaluates the block in the context of a Hooks::Factory,
-      # allowing before/after hook registration.
-      #
-      # @yield Block with before/after DSL calls
-      # @return [void]
-      #
-      # @example
-      #   extensions do
-      #     before :actions, AuthorizationExtension
-      #     after :outputs, LoggingExtension
-      #   end
-      def extensions(&block)
-        @stroma_hooks_factory ||= Hooks::Factory.new(stroma.hooks)
-        @stroma_hooks_factory.instance_eval(&block)
-      end
-    end
-  end
-end