stroma 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68cbb11810b858b8c7ae037857a017f5a9c912b60016ecaf87d3e7d7c7f31ac3
-  data.tar.gz: 02ef57657805b08bfed9b3c050621aa9f0b1f5afd8fc1461f4cf70c724ebfef4
+  metadata.gz: d3d83cec4af7649ab328cdae2c74b06a2f9d094cb755d469d594b0327fa1a279
+  data.tar.gz: 68191a403cccd3a6be19db18034df1b662d84dda0f587061c071b8e8bb34b787
 SHA512:
-  metadata.gz: b0f29a4456d77075e4a13933ae67e2e28ef03de467b8dc67dffe3a967d35b8af46c9f9211a610421f93262848771a9df034d3e548dd6e31e856d7f09ac70e788
-  data.tar.gz: 6659c659788fa76f2a730230fa38a0e92d009fcbe6ac1df9c7a5ec78ddd892dd3a97a6f0e96052f12d49cb144b74280dd89511efa0eeb31527ae9b98733d2726
+  metadata.gz: 29a687436d804c7677f2efcb4d51c26afd53511320a920da45e8d65b31b54d3c490cf936e11968d9a0e3cc5a90fdf1b2e68e9e0e0083cd6714d6e1241961c09e
+  data.tar.gz: eaba7ef983b606516eddd337205f6d7dd76845aff25bf3708fe6d1719629af013dff1a6e56ce3d038515e99911b6e952ee93ebdc3abc07bed6fc81fb97be71a1

data/README.md

@@ -1,3 +1,114 @@
-# Stroma
+<h1 align="center">Stroma</h1>
 
-Soon
+<p align="center">
+  A foundation for building modular, extensible DSLs in Ruby.
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/stroma"><img src="https://img.shields.io/gem/v/stroma?logo=rubygems&logoColor=fff" alt="Gem version"></a>
+  <a href="https://github.com/servactory/stroma/releases"><img src="https://img.shields.io/github/release-date/servactory/stroma" alt="Release Date"></a>
+  <a href="https://rubygems.org/gems/stroma"><img src="https://img.shields.io/gem/dt/stroma" alt="Downloads"></a>
+  <a href="https://www.ruby-lang.org"><img src="https://img.shields.io/badge/Ruby-3.2+-red" alt="Ruby version"></a>
+</p>
+
+<!--
+## 📚 Documentation
+
+See [stroma.servactory.com](https://stroma.servactory.com) for documentation, including:
+
+- Architecture overview
+- Registry and DSL modules
+- Hooks and extensions
+- Settings hierarchy
+- API reference
+-->
+
+## 💡 Why Stroma?
+
+Building modular DSLs shouldn't require reinventing the wheel. Stroma provides a structured approach for library authors to compose DSL modules with:
+
+- 🔌 **Module Registration** - Register DSL modules at boot time, compose them into a unified interface
+- 🧱 **Structured Composition** - Include all registered modules automatically via single DSL entry point
+- 🏛️ **Inheritance Safe** - Per-class state isolation with automatic deep copying
+- 🪝 **Extension Hooks** - Optional before/after hooks for user customization
+- ⚙️ **Extension Settings** - Three-level hierarchical storage for extension configuration
+- 🔒 **Thread Safe** - Immutable registry after finalization, safe concurrent reads
+
+## 🧬 Concept
+
+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
+
+## 🚀 Quick Start
+
+### Installation
+
+```ruby
+gem "stroma"
+```
+
+### 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
+  end
+end
+```
+
+### Create base class
+
+```ruby
+module MyLib
+  class Base
+    include MyLib::DSL
+  end
+end
+```
+
+### Usage
+
+```ruby
+class UserService < MyLib::Base
+  input :email, type: String
+
+  make :create_user
+
+  private
+
+  def create_user
+    # implementation
+  end
+end
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Check out our [Contributing Guide](https://github.com/servactory/stroma/blob/main/CONTRIBUTING.md) to get started.
+
+**Ways to contribute:**
+- 🐛 Report bugs and issues
+- 💡 Suggest new features
+- 📝 Improve documentation
+- 🧪 Add test cases
+- 🔧 Submit pull requests
+
+## 🙏 Acknowledgments
+
+Special thanks to all our [contributors](https://github.com/servactory/stroma/graphs/contributors)!
+
+## 📄 License
+
+Stroma is available as open source under the terms of the [MIT License](./LICENSE).

data/lib/stroma/dsl.rb

@@ -0,0 +1,124 @@
+# 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

data/lib/stroma/entry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Stroma
+  # Represents a registered DSL entry in the Stroma registry.
+  #
+  # ## Purpose
+  #
+  # Immutable value object that holds information about a DSL module
+  # registered in the Stroma system. Each entry has a unique key
+  # and references a Module that will be included in service classes.
+  #
+  # ## Attributes
+  #
+  # - `key` (Symbol): Unique identifier for the DSL module (:inputs, :outputs, :actions)
+  # - `extension` (Module): The actual DSL module to be included
+  #
+  # ## Usage
+  #
+  # Entries are created internally by Registry.register:
+  #
+  # ```ruby
+  # Stroma::Registry.register(:inputs, MyInputsDSL)
+  # # Creates: Entry.new(key: :inputs, extension: MyInputsDSL)
+  # ```
+  #
+  # ## Immutability
+  #
+  # Entry is immutable (Data object) - once created, it cannot be modified.
+  Entry = Data.define(:key, :extension)
+end

data/lib/stroma/exceptions/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Exceptions
+    # Base exception class for all Stroma-specific exceptions
+    #
+    # ## Purpose
+    #
+    # Serves as the parent class for all custom exceptions in the Stroma subsystem.
+    # Allows catching all Stroma-related exceptions with a single rescue clause.
+    #
+    # ## Usage
+    #
+    # All Stroma exceptions inherit from this base class:
+    #
+    # ```ruby
+    # begin
+    #   Stroma::Registry.register(:custom, CustomModule)
+    # rescue Stroma::Exceptions::Base => e
+    #   # Catches any Stroma-specific exception
+    #   handle_stroma_error(e)
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Can be used in application error handlers for centralized error handling:
+    #
+    # ```ruby
+    # rescue_from Stroma::Exceptions::Base, with: :handle_stroma_error
+    # ```
+    #
+    # ## Subclasses
+    #
+    # - RegistryFrozen - Raised when modifying a finalized registry
+    # - RegistryNotFinalized - Raised when accessing registry before finalization
+    # - KeyAlreadyRegistered - Raised when registering a duplicate key
+    # - UnknownHookTarget - Raised when using an invalid hook target key
+    # - InvalidHookType - Raised when using an invalid hook type (:before/:after)
+    class Base < StandardError
+    end
+  end
+end

data/lib/stroma/exceptions/invalid_hook_type.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Exceptions
+    # Raised when an invalid hook type is provided.
+    #
+    # ## Purpose
+    #
+    # Ensures that only valid hook types (:before, :after) are used
+    # when creating Stroma::Hooks::Hook objects. Provides fail-fast
+    # behavior during class definition rather than silent failures at runtime.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # # This will raise InvalidHookType:
+    # Stroma::Hooks::Hook.new(
+    #   type: :invalid,
+    #   target_key: :actions,
+    #   extension: MyModule
+    # )
+    # # => Stroma::Exceptions::InvalidHookType:
+    # #    Invalid hook type: :invalid. Valid types: :before, :after
+    # ```
+    class InvalidHookType < Base; end
+  end
+end

data/lib/stroma/exceptions/key_already_registered.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Exceptions
+    # Raised when registering a duplicate key in the registry
+    #
+    # ## Purpose
+    #
+    # Indicates that a DSL module key has already been registered.
+    # Each DSL module must have a unique key in the registry.
+    #
+    # ## Usage
+    #
+    # Raised when attempting to register a duplicate key:
+    #
+    # ```ruby
+    # Stroma::Registry.register(:inputs, Inputs::DSL)
+    # Stroma::Registry.register(:inputs, AnotherModule)
+    # # Raises: Stroma::Exceptions::KeyAlreadyRegistered
+    # ```
+    #
+    # ## Integration
+    #
+    # This exception typically indicates a configuration error - each
+    # DSL module should only be registered once. Check for duplicate
+    # registrations in your initialization code.
+    class KeyAlreadyRegistered < Base
+    end
+  end
+end

data/lib/stroma/exceptions/registry_frozen.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Exceptions
+    # Raised when attempting to modify a finalized registry
+    #
+    # ## Purpose
+    #
+    # Indicates that the Stroma::Registry has been finalized and cannot accept
+    # new module registrations. The registry is finalized once during gem
+    # initialization and remains immutable thereafter.
+    #
+    # ## Usage
+    #
+    # Raised when attempting to register modules after finalize!:
+    #
+    # ```ruby
+    # Stroma::Registry.finalize!
+    # Stroma::Registry.register(:custom, CustomModule)
+    # # Raises: Stroma::Exceptions::RegistryFrozen
+    # ```
+    #
+    # ## Integration
+    #
+    # This exception typically indicates a programming error - module
+    # registration should only occur during application boot, before
+    # any service classes are defined.
+    class RegistryFrozen < Base
+    end
+  end
+end

data/lib/stroma/exceptions/registry_not_finalized.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Exceptions
+    # Raised when accessing registry before finalization
+    #
+    # ## Purpose
+    #
+    # Indicates that the Stroma::Registry was accessed before finalize! was called.
+    # The registry must be finalized before it can be used to ensure all DSL modules
+    # are registered in the correct order.
+    #
+    # ## Usage
+    #
+    # Raised when accessing registry methods before finalization:
+    #
+    # ```ruby
+    # # Before finalize! is called
+    # Stroma::Registry.entries
+    # # Raises: Stroma::Exceptions::RegistryNotFinalized
+    # ```
+    #
+    # ## Integration
+    #
+    # This exception typically indicates that Stroma::DSL module was not
+    # properly loaded. Ensure stroma gem is properly required before
+    # defining service classes.
+    class RegistryNotFinalized < Base
+    end
+  end
+end

data/lib/stroma/exceptions/unknown_hook_target.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Exceptions
+    # Raised when using an invalid hook target key
+    #
+    # ## Purpose
+    #
+    # Indicates that an unknown key was used as a hook target in the
+    # extensions block. Only registered DSL module keys can be used
+    # as hook targets.
+    #
+    # ## Usage
+    #
+    # Raised when using an invalid key in extensions block:
+    #
+    # ```ruby
+    # # Library Base class (includes Stroma::DSL via library's DSL module)
+    # class MyLib::Base
+    #   include MyLib::DSL  # MyLib::DSL includes Stroma::DSL
+    #
+    #   extensions do
+    #     before :unknown_key, SomeModule
+    #     # Raises: Stroma::Exceptions::UnknownHookTarget
+    #   end
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Valid hook target keys are determined by registered DSL modules.
+    # Check Stroma::Registry.keys for the list of valid targets.
+    class UnknownHookTarget < Base
+    end
+  end
+end

data/lib/stroma/hooks/applier.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Hooks
+    # Applies registered hooks to a target class.
+    #
+    # ## 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.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # applier = Stroma::Hooks::Applier.new(ChildService, hooks)
+    # 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.
+    class Applier
+      # 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)
+        @target_class = target_class
+        @hooks = hooks
+      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.
+      #
+      # @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
+
+          @hooks.after(entry.key).each do |hook|
+            @target_class.include(hook.extension)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stroma/hooks/collection.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Hooks
+    # Mutable collection manager for Hook objects.
+    #
+    # ## Purpose
+    #
+    # Stores Hook objects and provides query methods to retrieve hooks
+    # by type and target key. Supports proper duplication during class
+    # inheritance to ensure configuration isolation.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # hooks = Stroma::Hooks::Collection.new
+    # hooks.add(:before, :actions, MyModule)
+    # hooks.add(:after, :actions, AnotherModule)
+    #
+    # hooks.before(:actions)  # => [Hook(...)]
+    # hooks.after(:actions)   # => [Hook(...)]
+    # hooks.empty?            # => false
+    # hooks.size              # => 2
+    # ```
+    #
+    # ## Integration
+    #
+    # Stored in Stroma::State and used by
+    # Stroma::Hooks::Applier to apply hooks to classes.
+    # Properly duplicated during class inheritance via initialize_dup.
+    class Collection
+      extend Forwardable
+
+      # @!method each
+      #   Iterates over all hooks in the collection.
+      #   @yield [Hook] Each hook in the collection
+      # @!method map
+      #   Maps over all hooks in the collection.
+      #   @yield [Hook] Each hook in the collection
+      #   @return [Array] Mapped results
+      # @!method size
+      #   Returns the number of hooks in the collection.
+      #   @return [Integer] Number of hooks
+      # @!method empty?
+      #   Checks if the collection is empty.
+      #   @return [Boolean] true if no hooks registered
+      def_delegators :@collection, :each, :map, :size, :empty?
+
+      # Creates a new hooks collection.
+      #
+      # @param collection [Set] Initial collection of hooks (default: empty Set)
+      def initialize(collection = Set.new)
+        @collection = collection
+      end
+
+      # Creates a deep copy during inheritance.
+      #
+      # @param original [Collection] The original collection being duplicated
+      # @return [void]
+      def initialize_dup(original)
+        super
+        @collection = original.instance_variable_get(:@collection).dup
+      end
+
+      # Adds a new hook to the collection.
+      #
+      # @param type [Symbol] Hook type (:before or :after)
+      # @param target_key [Symbol] Registry key to hook into
+      # @param extension [Module] Extension module to include
+      # @return [Set] The updated collection
+      #
+      # @example
+      #   hooks.add(:before, :actions, ValidationModule)
+      def add(type, target_key, extension)
+        @collection << Hook.new(type:, target_key:, extension:)
+      end
+
+      # Returns all before hooks for a given key.
+      #
+      # @param key [Symbol] The target key to filter by
+      # @return [Array<Hook>] Hooks that run before the target
+      #
+      # @example
+      #   hooks.before(:actions)  # => [Hook(type: :before, ...)]
+      def before(key)
+        @collection.select { |hook| hook.before? && hook.target_key == key }
+      end
+
+      # Returns all after hooks for a given key.
+      #
+      # @param key [Symbol] The target key to filter by
+      # @return [Array<Hook>] Hooks that run after the target
+      #
+      # @example
+      #   hooks.after(:actions)  # => [Hook(type: :after, ...)]
+      def after(key)
+        @collection.select { |hook| hook.after? && hook.target_key == key }
+      end
+    end
+  end
+end

data/lib/stroma/hooks/factory.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Hooks
+    # DSL interface for registering hooks in extensions block.
+    #
+    # ## 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.
+    #
+    # ## 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
+    #
+    #   extensions do
+    #     before :actions, ValidationModule
+    #     after :outputs, LoggingModule
+    #   end
+    # end
+    # ```
+    #
+    # ## Integration
+    #
+    # Created by DSL.extensions method and receives instance_eval of the block.
+    # Validates keys against Registry.keys and raises UnknownHookTarget
+    # for invalid keys.
+    class Factory
+      # Creates a new factory for registering hooks.
+      #
+      # @param hooks [Collection] The hooks collection to add to
+      def initialize(hooks)
+        @hooks = hooks
+      end
+
+      # Registers one or more before hooks for a target key.
+      #
+      # @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
+      #
+      # @example
+      #   before :actions, ValidationModule, AuthorizationModule
+      def before(key, *extensions)
+        validate_key!(key)
+        extensions.each { |extension| @hooks.add(:before, key, extension) }
+      end
+
+      # Registers one or more after hooks for a target key.
+      #
+      # @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
+      #
+      # @example
+      #   after :outputs, LoggingModule, AuditModule
+      def after(key, *extensions)
+        validate_key!(key)
+        extensions.each { |extension| @hooks.add(:after, key, extension) }
+      end
+
+      private
+
+      # Validates that the key exists in the Registry.
+      #
+      # @param key [Symbol] The key to validate
+      # @raise [Exceptions::UnknownHookTarget] If key is not registered
+      def validate_key!(key)
+        return if Registry.key?(key)
+
+        raise Exceptions::UnknownHookTarget,
+              "Unknown hook target: #{key.inspect}. " \
+              "Valid keys: #{Registry.keys.map(&:inspect).join(', ')}"
+      end
+    end
+  end
+end

data/lib/stroma/hooks/hook.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Hooks
+    # Valid hook types for Hook validation.
+    VALID_HOOK_TYPES = %i[before after].freeze
+    private_constant :VALID_HOOK_TYPES
+
+    # Immutable value object representing a hook configuration.
+    #
+    # ## Purpose
+    #
+    # Defines when and where an extension module should be included
+    # relative to a registered DSL module. Hook is immutable - once
+    # created, it cannot be modified.
+    #
+    # ## Attributes
+    #
+    # @!attribute [r] type
+    #   @return [Symbol] Either :before or :after
+    # @!attribute [r] target_key
+    #   @return [Symbol] Key of the DSL module to hook into (:inputs, :actions, etc.)
+    # @!attribute [r] extension
+    #   @return [Module] The module to include at the hook point
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # hook = Stroma::Hooks::Hook.new(
+    #   type: :before,
+    #   target_key: :actions,
+    #   extension: MyExtension
+    # )
+    # hook.before?  # => true
+    # hook.after?   # => false
+    # ```
+    #
+    # ## Immutability
+    #
+    # Hook is a Data object - frozen and immutable after creation.
+    Hook = Data.define(:type, :target_key, :extension) do
+      # Initializes a new Hook with validation.
+      #
+      # @param type [Symbol] Hook type (:before or :after)
+      # @param target_key [Symbol] Registry key to hook into
+      # @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)
+          raise Exceptions::InvalidHookType,
+                "Invalid hook type: #{type.inspect}. Valid types: #{VALID_HOOK_TYPES.map(&:inspect).join(', ')}"
+        end
+
+        super
+      end
+
+      # Checks if this is a before hook.
+      #
+      # @return [Boolean] true if type is :before
+      def before?
+        type == :before
+      end
+
+      # Checks if this is an after hook.
+      #
+      # @return [Boolean] true if type is :after
+      def after?
+        type == :after
+      end
+    end
+  end
+end

data/lib/stroma/registry.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Stroma
+  # Manages global registration of DSL modules for Stroma.
+  #
+  # ## Purpose
+  #
+  # Singleton registry that stores all DSL modules that will be included
+  # in service classes. Implements two-phase lifecycle: registration
+  # followed by finalization.
+  #
+  # ## Usage
+  #
+  # ```ruby
+  # # During gem initialization:
+  # Stroma::Registry.register(:inputs, Inputs::DSL)
+  # Stroma::Registry.register(:outputs, Outputs::DSL)
+  # Stroma::Registry.finalize!
+  #
+  # # After finalization:
+  # Stroma::Registry.keys       # => [:inputs, :outputs]
+  # Stroma::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.
+  class Registry
+    include Singleton
+
+    class << self
+      delegate :register,
+               :finalize!,
+               :entries,
+               :keys,
+               :key?,
+               to: :instance
+    end
+
+    def initialize
+      @entries = []
+      @finalized = false
+    end
+
+    def register(key, extension)
+      raise Exceptions::RegistryFrozen, "Registry is finalized" if @finalized
+
+      if @entries.any? { |e| e.key == key }
+        raise Exceptions::KeyAlreadyRegistered, "Key #{key.inspect} already registered"
+      end
+
+      @entries << Entry.new(key:, extension:)
+    end
+
+    def finalize!
+      return if @finalized
+
+      @entries.freeze
+      @finalized = true
+    end
+
+    def entries
+      ensure_finalized!
+      @entries
+    end
+
+    def keys
+      ensure_finalized!
+      @entries.map(&:key)
+    end
+
+    def key?(key)
+      ensure_finalized!
+      @entries.any? { |e| e.key == key }
+    end
+
+    private
+
+    def ensure_finalized!
+      return if @finalized
+
+      raise Exceptions::RegistryNotFinalized,
+            "Registry not finalized. Call Stroma::Registry.finalize! after registration."
+    end
+  end
+end

data/lib/stroma/settings/collection.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Settings
+    # Top-level hierarchical container for extension settings.
+    #
+    # ## Purpose
+    #
+    # Provides two-level hierarchical access to extension settings:
+    # registry_key -> extension_name -> setting values.
+    # Auto-vivifies RegistrySettings on first access.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # settings = Stroma::Settings::Collection.new
+    # settings[:actions][:authorization][:method_name] = :authorize
+    # settings[:actions][:transactional][:enabled] = true
+    #
+    # settings.keys    # => [:actions]
+    # settings.empty?  # => false
+    # settings.to_h    # => { actions: { authorization: { method_name: :authorize }, ... } }
+    # ```
+    #
+    # ## Integration
+    #
+    # Stored in Stroma::State alongside Hooks::Collection.
+    # Accessed via `stroma.settings` in service classes.
+    # Properly duplicated during class inheritance via initialize_dup.
+    class Collection
+      extend Forwardable
+
+      # @!method each
+      #   Iterates over all registry key settings.
+      #   @yield [key, settings] Each registry key and its RegistrySettings
+      # @!method keys
+      #   Returns all registry keys with settings.
+      #   @return [Array<Symbol>] List of registry keys
+      # @!method size
+      #   Returns the number of registry keys configured.
+      #   @return [Integer] Number of registry keys
+      # @!method empty?
+      #   Checks if no settings are configured.
+      #   @return [Boolean] true if empty
+      # @!method map
+      #   Maps over all registry key settings.
+      #   @yield [key, settings] Each registry key and its RegistrySettings
+      #   @return [Array] Mapped results
+      def_delegators :@storage, :each, :keys, :size, :empty?, :map
+
+      # Creates a new settings collection.
+      #
+      # @param storage [Hash] Initial storage (default: empty Hash)
+      def initialize(storage = {})
+        @storage = storage
+      end
+
+      # Creates a deep copy during inheritance.
+      #
+      # @param original [Collection] The original collection being duplicated
+      # @return [void]
+      def initialize_dup(original)
+        super
+        @storage = original.instance_variable_get(:@storage).transform_values(&:dup)
+      end
+
+      # Accesses or creates RegistrySettings for a registry key.
+      #
+      # Auto-vivifies a new RegistrySettings on first access.
+      #
+      # @param registry_key [Symbol] The registry key (e.g., :actions)
+      # @return [RegistrySettings] Settings for that registry key
+      #
+      # @example
+      #   settings[:actions][:authorization][:method_name] = :authorize
+      def [](registry_key)
+        @storage[registry_key.to_sym] ||= RegistrySettings.new
+      end
+
+      # Converts to a nested Hash.
+      #
+      # @return [Hash] Deep nested hash of all settings
+      def to_h
+        @storage.transform_values(&:to_h)
+      end
+    end
+  end
+end

data/lib/stroma/settings/registry_settings.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Settings
+    # Collection of Setting objects for one registry key.
+    #
+    # ## Purpose
+    #
+    # Groups extension settings by registry key (e.g., :actions).
+    # Provides auto-vivifying access to individual Setting objects.
+    # This is the middle layer in the settings hierarchy.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # settings = Stroma::Settings::RegistrySettings.new
+    # settings[:authorization][:method_name] = :authorize
+    # settings[:transactional][:enabled] = true
+    #
+    # settings.keys   # => [:authorization, :transactional]
+    # settings.empty? # => false
+    # ```
+    #
+    # ## Integration
+    #
+    # Used by Collection as second-level container.
+    # Properly duplicated during class inheritance via initialize_dup.
+    class RegistrySettings
+      extend Forwardable
+
+      # @!method each
+      #   Iterates over all extension settings.
+      #   @yield [name, setting] Each extension name and its Setting
+      # @!method keys
+      #   Returns all extension names.
+      #   @return [Array<Symbol>] List of extension names
+      # @!method size
+      #   Returns the number of extensions configured.
+      #   @return [Integer] Number of extensions
+      # @!method empty?
+      #   Checks if no extensions are configured.
+      #   @return [Boolean] true if empty
+      # @!method map
+      #   Maps over all extension settings.
+      #   @yield [name, setting] Each extension name and its Setting
+      #   @return [Array] Mapped results
+      def_delegators :@storage, :each, :keys, :size, :empty?, :map
+
+      # Creates a new registry settings container.
+      #
+      # @param storage [Hash] Initial storage (default: empty Hash)
+      def initialize(storage = {})
+        @storage = storage
+      end
+
+      # Creates a deep copy during inheritance.
+      #
+      # @param original [RegistrySettings] The original being duplicated
+      # @return [void]
+      def initialize_dup(original)
+        super
+        @storage = original.instance_variable_get(:@storage).transform_values(&:dup)
+      end
+
+      # Accesses or creates a Setting for an extension.
+      #
+      # Auto-vivifies a new Setting on first access.
+      #
+      # @param extension_name [Symbol] The extension name
+      # @return [Setting] The extension's setting container
+      #
+      # @example
+      #   settings[:authorization][:method_name] = :authorize
+      def [](extension_name)
+        @storage[extension_name.to_sym] ||= Setting.new
+      end
+
+      # Converts to a nested Hash.
+      #
+      # @return [Hash] Nested hash of all settings
+      def to_h
+        @storage.transform_values(&:to_h)
+      end
+    end
+  end
+end

data/lib/stroma/settings/setting.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Stroma
+  module Settings
+    # Dynamic key-value storage for extension configuration.
+    #
+    # ## Purpose
+    #
+    # Provides a Hash-based container for storing extension-specific
+    # configuration data. Uses Forwardable delegation for consistent API.
+    # This is the leaf-level container in the settings hierarchy.
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # setting = Stroma::Settings::Setting.new
+    # setting[:method_name] = :authorize
+    # setting[:method_name]  # => :authorize
+    # setting.key?(:method_name)  # => true
+    # ```
+    #
+    # ## Integration
+    #
+    # Used by RegistrySettings to store individual extension settings.
+    # Properly duplicated during class inheritance via initialize_dup.
+    class Setting
+      extend Forwardable
+
+      # @!method [](key)
+      #   Retrieves a value by key.
+      #   @param key [Symbol] The key to look up
+      #   @return [Object, nil] The stored value or nil
+      # @!method []=(key, value)
+      #   Stores a value by key.
+      #   @param key [Symbol] The key to store under
+      #   @param value [Object] The value to store
+      # @!method key?(key)
+      #   Checks if a key exists.
+      #   @param key [Symbol] The key to check
+      #   @return [Boolean] true if key exists
+      # @!method keys
+      #   Returns all stored keys.
+      #   @return [Array<Symbol>] List of keys
+      # @!method each
+      #   Iterates over all key-value pairs.
+      #   @yield [key, value] Each stored pair
+      # @!method empty?
+      #   Checks if no values are stored.
+      #   @return [Boolean] true if empty
+      # @!method size
+      #   Returns the number of stored values.
+      #   @return [Integer] Number of entries
+      # @!method map
+      #   Maps over all key-value pairs.
+      #   @yield [key, value] Each stored pair
+      #   @return [Array] Mapped results
+      def_delegators :@data, :[], :[]=, :key?, :keys, :each, :empty?, :size, :map
+
+      # Creates a new setting container.
+      #
+      # @param data [Hash] Initial data (default: empty Hash)
+      def initialize(data = {})
+        @data = data
+      end
+
+      # Creates a deep copy during inheritance.
+      #
+      # @param original [Setting] The original setting being duplicated
+      # @return [void]
+      def initialize_dup(original)
+        super
+        @data = deep_dup(original.instance_variable_get(:@data))
+      end
+
+      # Converts to a plain Hash.
+      #
+      # @return [Hash] Deep copy of internal data
+      def to_h
+        deep_dup(@data)
+      end
+
+      # Fetches a value with optional default.
+      #
+      # @param key [Symbol] The key to fetch
+      # @param args [Array] Optional default value
+      # @yield Optional block for default value
+      # @return [Object] The fetched value or default
+      #
+      # @example
+      #   setting.fetch(:method_name, :default_method)
+      #   setting.fetch(:method_name) { :computed_default }
+      def fetch(key, *args, &block)
+        @data.fetch(key.to_sym, *args, &block)
+      end
+
+      private
+
+      # Recursively duplicates nested Hash and Array structures.
+      #
+      # @param obj [Object] The object to duplicate
+      # @return [Object] Deep copy of the object
+      def deep_dup(obj)
+        case obj
+        when Hash then obj.transform_values { |v| deep_dup(v) }
+        when Array then obj.map { |v| deep_dup(v) }
+        else obj.respond_to?(:dup) ? obj.dup : obj
+        end
+      end
+    end
+  end
+end

data/lib/stroma/state.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Stroma
+  # Holds the complete Stroma state for a service class.
+  #
+  # ## Purpose
+  #
+  # Central container that stores:
+  # - Hooks collection for before/after extension points
+  # - Settings collection for extension-specific configuration
+  #
+  # Each service class has its own State instance, duplicated during
+  # inheritance to ensure independent configuration.
+  #
+  # ## Usage
+  #
+  # Accessed via `stroma` method in classes that include Stroma::DSL.
+  # Library authors include Stroma::DSL in their DSL module:
+  #
+  # ```ruby
+  # # Library DSL module includes Stroma::DSL
+  # module MyLib::DSL
+  #   def self.included(base)
+  #     base.include(Stroma::DSL)
+  #   end
+  # end
+  #
+  # # Library Base class includes library's DSL
+  # class MyLib::Base
+  #   include MyLib::DSL
+  #
+  #   stroma.hooks.before(:actions)
+  #   stroma.settings[:actions][:authorization][:method_name]
+  # end
+  # ```
+  #
+  # ## Integration
+  #
+  # Stored as @stroma instance variable on each service class.
+  # Duplicated in DSL.inherited to provide inheritance isolation.
+  class State
+    # @!attribute [r] hooks
+    #   @return [Hooks::Collection] The hooks collection for this class
+    # @!attribute [r] settings
+    #   @return [Settings::Collection] The settings collection for this class
+    attr_reader :hooks, :settings
+
+    # Creates a new State with empty collections.
+    def initialize
+      @hooks = Hooks::Collection.new
+      @settings = Settings::Collection.new
+    end
+
+    # Creates a deep copy during inheritance.
+    #
+    # Ensures child classes have independent hooks and settings
+    # that don't affect the parent class.
+    #
+    # @param original [State] The original state being duplicated
+    # @return [void]
+    def initialize_dup(original)
+      super
+      @hooks = original.instance_variable_get(:@hooks).dup
+      @settings = original.instance_variable_get(:@settings).dup
+    end
+  end
+end

data/lib/stroma/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stroma
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -79,7 +93,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.9'
-description: Stroma hook system
+description: A structured approach to composing DSL modules for Ruby libraries with
+  optional extension hooks
 email:
 - profox.rus@gmail.com
 executables: []
@@ -89,7 +104,24 @@ files:
 - README.md
 - Rakefile
 - lib/stroma.rb
+- lib/stroma/dsl.rb
 - lib/stroma/engine.rb
+- lib/stroma/entry.rb
+- lib/stroma/exceptions/base.rb
+- lib/stroma/exceptions/invalid_hook_type.rb
+- lib/stroma/exceptions/key_already_registered.rb
+- lib/stroma/exceptions/registry_frozen.rb
+- lib/stroma/exceptions/registry_not_finalized.rb
+- lib/stroma/exceptions/unknown_hook_target.rb
+- lib/stroma/hooks/applier.rb
+- lib/stroma/hooks/collection.rb
+- lib/stroma/hooks/factory.rb
+- lib/stroma/hooks/hook.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/version.rb
 homepage: https://github.com/servactory/stroma
 licenses:
@@ -115,5 +147,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.7.2
 specification_version: 4
-summary: Stroma hook system
+summary: Foundation for building modular, extensible DSLs
 test_files: []