hybrid-state-model 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ccb639c4ad5854bb0d7d81dd251af7d7bff899112e2a19588b004b2a5c62d4b7
+  data.tar.gz: 00a6d76e7b17bca056d3cc61cc3a77d0cd37aadb1246bff82c6c1c1c4becf3a6
+SHA512:
+  metadata.gz: 869f995dd5b782d748a2c64ee1f6c6419fa73a906897ea9579d1d8872ba3ba3ce415a8f5ee1b1a19ebaf6e6be56d7c04850a8bd9afda82a3e6c778e8d1e9694f
+  data.tar.gz: 29f58c5169ee5c1444931632799e118647387016bab884b91bfffd592de5ce6f2d02b83d83db5c54c7f054dd5f9de4aa82f1e951e91e3eac8e9b4908824a9611

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-01-01
+
+### Added
+- Initial release of hybrid-state-model
+- Two-layer state system (primary state + micro state)
+- DSL for defining states and mappings
+- Transition methods: `promote!`, `advance!`, `reset_micro!`, `transition!`
+- Query scopes: `in_primary`, `in_micro`, `with_primary_and_micro`, `with_micro`, `without_micro`
+- Automatic state validation
+- Callbacks: `before_primary_transition`, `after_primary_transition`, `before_micro_transition`, `after_micro_transition`
+- Optional metrics tracking for time spent in states
+- Support for auto-resetting micro state when primary state changes
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,308 @@
+# Hybrid State Model
+
+A revolutionary two-layer hierarchical state system for Ruby models. Perfect for complex workflows that are too complex for flat state machines but don't need full orchestration engines.
+
+## 🌟 The Big Idea
+
+**hybrid-state-model** introduces a two-layer state system:
+
+- **Primary State** — high-level lifecycle (e.g., `pending`, `active`, `shipped`, `delivered`)
+- **Secondary Micro-State** — small step within the primary state (e.g., `verifying_email`, `awaiting_payment`, `in_transit`, `out_for_delivery`)
+
+This creates a simple but powerful hierarchical state system that reduces complexity instead of adding it.
+
+## ✨ Features
+
+- 🎯 **Two-layer state system** — Primary states with nested micro-states
+- 🔒 **Automatic constraints** — Micro-states are validated against their primary state
+- 🚀 **Flexible transitions** — `promote!`, `advance!`, `reset_micro!`, and `transition!`
+- 🔍 **Querying capabilities** — `in_primary`, `in_micro`, `with_primary_and_micro` scopes
+- 📊 **Metrics tracking** — Track time spent in each state (optional)
+- 🎛️ **Callbacks** — `before_primary_transition`, `after_primary_transition`, etc.
+- ✅ **ActiveRecord integration** — Works seamlessly with Rails models
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hybrid-state-model'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install hybrid-state-model
+```
+
+## 🚀 Quick Start
+
+### 1. Create your migration
+
+```ruby
+class CreateOrders < ActiveRecord::Migration[7.0]
+  def change
+    create_table :orders do |t|
+      t.string :status          # Primary state
+      t.string :sub_status      # Micro state
+      t.text :state_metrics     # Optional: for metrics tracking
+      
+      t.timestamps
+    end
+  end
+end
+```
+
+### 2. Define your model
+
+```ruby
+class Order < ActiveRecord::Base
+  include HybridStateModel
+
+  hybrid_state do
+    # Define primary state field and possible values
+    primary :status, %i[pending processing shipped delivered returned]
+
+    # Define micro state field and possible values
+    micro :sub_status, %i[
+      awaiting_payment
+      fraud_check_passed
+      fraud_check_failed
+      ready_to_pack
+      packing
+      assigning_carrier
+      waiting_for_pickup
+      in_transit
+      out_for_delivery
+      inspection
+      return_processing
+      return_complete
+    ]
+
+    # Map which micro-states are allowed for each primary state
+    map status: :pending, sub_status: %i[awaiting_payment]
+    map status: :processing, sub_status: %i[fraud_check_passed fraud_check_failed ready_to_pack packing assigning_carrier]
+    map status: :shipped, sub_status: %i[waiting_for_pickup in_transit out_for_delivery]
+    map status: :returned, sub_status: %i[inspection return_processing return_complete]
+
+    # Optional: Reset micro state when primary state changes
+    when_primary_changes reset_micro: true
+
+    # Optional: Callbacks
+    before_primary_transition :shipped do
+      raise "Cannot ship without payment" unless paid?
+    end
+
+    after_primary_transition :delivered do
+      send_delivery_confirmation_email
+    end
+  end
+end
+```
+
+### 3. Use it!
+
+```ruby
+# Create an order
+order = Order.create!(status: :pending, sub_status: :awaiting_payment)
+
+# Promote to primary state (moves to next major state)
+order.promote!(:processing)
+# => status: :processing, sub_status: nil (reset because of when_primary_changes)
+
+# Advance micro state (moves within current primary state)
+order.advance!(:ready_to_pack)
+# => status: :processing, sub_status: :ready_to_pack
+
+# Transition both at once
+order.transition!(primary: :shipped, micro: :waiting_for_pickup)
+# => status: :shipped, sub_status: :waiting_for_pickup
+
+# Advance through micro states
+order.advance!(:in_transit)
+order.advance!(:out_for_delivery)
+
+# Promote to final state
+order.promote!(:delivered)
+
+# Querying
+Order.in_primary(:shipped)
+Order.in_micro(:in_transit)
+Order.with_primary_and_micro(primary: :shipped, micro: :out_for_delivery)
+Order.with_micro  # Orders that have a micro state
+Order.without_micro  # Orders without a micro state
+
+# Validation
+order.status = :delivered
+order.sub_status = :assigning_carrier  # ❌ Invalid! Will fail validation
+```
+
+## 📚 API Reference
+
+### DSL Methods
+
+#### `primary(field_name, states)`
+Defines the primary state field and its possible values.
+
+```ruby
+primary :status, %i[pending active inactive]
+```
+
+#### `micro(field_name, states)`
+Defines the micro state field and its possible values.
+
+```ruby
+micro :sub_status, %i[verifying_email awaiting_approval]
+```
+
+#### `map(primary_state:, micro_states:)`
+Maps which micro-states are allowed for a specific primary state.
+
+```ruby
+map status: :active, sub_status: %i[verifying_email awaiting_approval]
+```
+
+#### `when_primary_changes(reset_micro: true)`
+Automatically resets the micro state when the primary state changes.
+
+#### `before_primary_transition(states, &block)`
+Runs a callback before transitioning to the specified primary state(s).
+
+```ruby
+before_primary_transition :shipped do
+  validate_shipping_address
+end
+```
+
+#### `after_primary_transition(states, &block)`
+Runs a callback after transitioning to the specified primary state(s).
+
+#### `before_micro_transition(states, &block)`
+Runs a callback before transitioning to the specified micro state(s).
+
+#### `after_micro_transition(states, &block)`
+Runs a callback after transitioning to the specified micro state(s).
+
+### Instance Methods
+
+#### `promote!(new_primary_state, options = {})`
+Transitions to a new primary state. Automatically resets micro state if configured.
+
+```ruby
+order.promote!(:shipped)
+order.promote!(:delivered, skip_save: true)  # Don't save immediately
+```
+
+#### `advance!(new_micro_state, options = {})`
+Transitions to a new micro state within the current primary state.
+
+```ruby
+order.advance!(:in_transit)
+```
+
+#### `reset_micro!(options = {})`
+Resets the micro state to `nil`.
+
+```ruby
+order.reset_micro!
+```
+
+#### `transition!(primary:, micro:, options = {})`
+Transitions both primary and micro states at once.
+
+```ruby
+order.transition!(primary: :shipped, micro: :waiting_for_pickup)
+```
+
+#### `can_transition_to_primary?(state)`
+Checks if the record can transition to the specified primary state.
+
+#### `can_transition_to_micro?(state)`
+Checks if the record can transition to the specified micro state.
+
+### Query Scopes
+
+#### `in_primary(*states)`
+Finds records with the specified primary state(s).
+
+```ruby
+Order.in_primary(:shipped, :delivered)
+```
+
+#### `in_micro(*states)`
+Finds records with the specified micro state(s).
+
+```ruby
+Order.in_micro(:in_transit, :out_for_delivery)
+```
+
+#### `with_primary_and_micro(primary:, micro:)`
+Finds records with both the specified primary and micro states.
+
+```ruby
+Order.with_primary_and_micro(primary: :shipped, micro: :in_transit)
+```
+
+#### `with_micro`
+Finds records that have a micro state set.
+
+#### `without_micro`
+Finds records that don't have a micro state set.
+
+## 📊 Metrics Tracking
+
+If you add a `state_metrics` text/json column to your table, the gem will automatically track time spent in each state:
+
+```ruby
+# Migration
+add_column :orders, :state_metrics, :text
+
+# Usage
+order.state_metrics
+# => {
+#   "pending" => {"entered_at" => "...", "duration" => 120.5},
+#   "processing" => {"entered_at" => "...", "duration" => 300.0},
+#   "processing:ready_to_pack" => {"entered_at" => "...", "duration" => 60.0}
+# }
+
+order.time_in_primary_state(:processing)
+# => 300.0 (seconds)
+
+order.current_state_duration
+# => 45.2 (seconds in current state)
+```
+
+## 🎯 Use Cases
+
+### Logistics & Shipping
+```ruby
+primary :status, %i[pending processing shipped delivered]
+micro :sub_status, %i[ready_to_pack packing waiting_for_pickup in_transit out_for_delivery]
+```
+
+### Payment & Billing
+```ruby
+primary :status, %i[active suspended canceled]
+micro :sub_status, %i[verifying_card awaiting_payment retrying_charge]
+```
+
+### User Onboarding
+```ruby
+primary :status, %i[active pending]
+micro :sub_status, %i[verifying_email uploading_documents awaiting_approval]
+```
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/afshmini/hybrid-state-model.
+
+## 📝 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+

data/examples/order_example.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# Example: Order model with hybrid state
+#
+# This example demonstrates how to use hybrid-state-model
+# for an e-commerce order workflow
+
+require "active_record"
+require_relative "../lib/hybrid_state_model"
+
+# Setup database (in a real app, this would be a migration)
+ActiveRecord::Base.establish_connection(
+  adapter: "sqlite3",
+  database: ":memory:"
+)
+
+ActiveRecord::Schema.define do
+  create_table :orders do |t|
+    t.string :status
+    t.string :sub_status
+    t.text :state_metrics
+    t.boolean :paid, default: false
+    t.timestamps
+  end
+end
+
+class Order < ActiveRecord::Base
+  include HybridStateModel
+
+  hybrid_state do
+    # Define primary state (high-level lifecycle)
+    primary :status, %i[pending processing shipped delivered returned]
+
+    # Define micro state (steps within primary state)
+    micro :sub_status, %i[
+      awaiting_payment
+      fraud_check_passed
+      fraud_check_failed
+      ready_to_pack
+      packing
+      assigning_carrier
+      waiting_for_pickup
+      in_transit
+      out_for_delivery
+      inspection
+      return_processing
+      return_complete
+    ]
+
+    # Map which micro-states are allowed for each primary state
+    map status: :pending, sub_status: %i[awaiting_payment]
+    map status: :processing, sub_status: %i[fraud_check_passed fraud_check_failed ready_to_pack packing assigning_carrier]
+    map status: :shipped, sub_status: %i[waiting_for_pickup in_transit out_for_delivery]
+    map status: :returned, sub_status: %i[inspection return_processing return_complete]
+
+    # Automatically reset micro state when primary state changes
+    when_primary_changes reset_micro: true
+
+    # Callbacks
+    before_primary_transition :shipped do
+      raise "Cannot ship unpaid order" unless paid?
+    end
+
+    after_primary_transition :delivered do
+      puts "Order #{id} has been delivered!"
+    end
+  end
+end
+
+# Example usage
+if __FILE__ == $PROGRAM_NAME
+  puts "=== Hybrid State Model Example ===\n\n"
+
+  # Create an order
+  order = Order.create!(status: :pending, sub_status: :awaiting_payment, paid: false)
+  puts "1. Created order: #{order.status} / #{order.sub_status}"
+
+  # Mark as paid and move to processing
+  order.update!(paid: true)
+  order.promote!(:processing)
+  puts "2. Promoted to: #{order.status} / #{order.sub_status}"
+
+  # Advance through micro states
+  order.advance!(:ready_to_pack)
+  puts "3. Advanced to: #{order.status} / #{order.sub_status}"
+
+  order.advance!(:packing)
+  puts "4. Advanced to: #{order.status} / #{order.sub_status}"
+
+  # Transition both at once
+  order.transition!(primary: :shipped, micro: :waiting_for_pickup)
+  puts "5. Transitioned to: #{order.status} / #{order.sub_status}"
+
+  # Continue through shipping micro states
+  order.advance!(:in_transit)
+  puts "6. Advanced to: #{order.status} / #{order.sub_status}"
+
+  order.advance!(:out_for_delivery)
+  puts "7. Advanced to: #{order.status} / #{order.sub_status}"
+
+  # Final state
+  order.promote!(:delivered)
+  puts "8. Final state: #{order.status} / #{order.sub_status}"
+
+  # Query examples
+  puts "\n=== Query Examples ==="
+  puts "Orders in 'shipped' state: #{Order.in_primary(:shipped).count}"
+  puts "Orders with micro state 'in_transit': #{Order.in_micro(:in_transit).count}"
+
+  puts "\n=== Example Complete ==="
+end
+

data/hybrid-state-model.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/hybrid_state_model/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "hybrid-state-model"
+  spec.version = HybridStateModel::VERSION
+  spec.authors = ["Your Name"]
+  spec.email = ["your.email@example.com"]
+
+  spec.summary = "A two-layer hierarchical state system for Ruby models"
+  spec.description = <<~DESC
+    hybrid-state-model introduces a revolutionary two-layer state system:
+    Primary State (high-level lifecycle) and Secondary Micro-State (small steps within primary state).
+    Perfect for complex workflows that are too complex for flat state machines but don't need full orchestration.
+  DESC
+  spec.homepage = "https://github.com/afshmini/hybrid-state-model"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activerecord", ">= 5.2.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "sqlite3", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.21"
+end
+

data/lib/hybrid_state_model/core.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module HybridStateModel
+  module Core
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def hybrid_state_model?
+        true
+      end
+    end
+
+    def primary_state
+      state_machine.primary_field
+    end
+
+    def micro_state
+      state_machine.micro_field
+    end
+
+    def state_machine
+      self.class.state_machine
+    end
+
+    def primary_state_value
+      send(primary_state)
+    end
+
+    def micro_state_value
+      send(micro_state)
+    end
+
+    def valid_primary_state?(state)
+      state_machine.valid_primary_state?(state)
+    end
+
+    def valid_micro_state?(state)
+      state_machine.valid_micro_state?(state, primary_state_value)
+    end
+
+    def can_transition_to_primary?(new_state)
+      state_machine.can_transition_to_primary?(self, new_state)
+    end
+
+    def can_transition_to_micro?(new_micro_state)
+      state_machine.can_transition_to_micro?(self, new_micro_state)
+    end
+  end
+end
+

data/lib/hybrid_state_model/metrics.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "json"
+
+module HybridStateModel
+  module Metrics
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def has_state_metrics?
+        column_names.include?("state_metrics")
+      end
+    end
+
+    def track_state_changes
+      return unless persisted?
+
+      @state_changed = primary_state_changed? || micro_state_changed?
+      @old_primary = primary_state_was if primary_state_changed?
+      @old_micro = micro_state_was if micro_state_changed?
+    end
+
+    def record_state_metrics
+      return unless @state_changed
+
+      metrics = state_metrics_hash
+      current_time = Time.now
+
+      # Record exit time for old state
+      if @old_primary
+        metrics[@old_primary.to_s] ||= {}
+        metrics[@old_primary.to_s]["exited_at"] ||= current_time.iso8601
+        metrics[@old_primary.to_s]["duration"] ||= 0
+        if metrics[@old_primary.to_s]["entered_at"]
+          duration = current_time - Time.parse(metrics[@old_primary.to_s]["entered_at"])
+          metrics[@old_primary.to_s]["duration"] += duration
+        end
+      end
+
+      # Record entry time for new state
+      new_primary = primary_state_value
+      if new_primary
+        metrics[new_primary.to_s] ||= {}
+        metrics[new_primary.to_s]["entered_at"] = current_time.iso8601
+        metrics[new_primary.to_s]["duration"] ||= 0
+      end
+
+      # Record micro state metrics
+      if @old_micro && @old_primary
+        micro_key = "#{@old_primary}:#{@old_micro}"
+        metrics[micro_key] ||= {}
+        metrics[micro_key]["exited_at"] ||= current_time.iso8601
+        if metrics[micro_key]["entered_at"]
+          duration = current_time - Time.parse(metrics[micro_key]["entered_at"])
+          metrics[micro_key]["duration"] ||= 0
+          metrics[micro_key]["duration"] += duration
+        end
+      end
+
+      if micro_state_value && new_primary
+        micro_key = "#{new_primary}:#{micro_state_value}"
+        metrics[micro_key] ||= {}
+        metrics[micro_key]["entered_at"] = current_time.iso8601
+        metrics[micro_key]["duration"] ||= 0
+      end
+
+      # Store metrics if column exists
+      if self.class.has_state_metrics?
+        self.state_metrics = metrics.to_json
+      end
+
+      @state_changed = false
+    end
+
+    def state_metrics
+      return {} unless self.class.has_state_metrics?
+
+      json = read_attribute(:state_metrics)
+      return {} if json.blank?
+
+      JSON.parse(json)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def state_metrics_hash
+      state_metrics
+    end
+
+    def time_in_primary_state(state = nil)
+      state ||= primary_state_value
+      metrics = state_metrics_hash[state.to_s] || {}
+      metrics["duration"] || 0
+    end
+
+    def time_in_micro_state(primary_state, micro_state)
+      key = "#{primary_state}:#{micro_state}"
+      metrics = state_metrics_hash[key] || {}
+      metrics["duration"] || 0
+    end
+
+    def current_state_duration
+      return 0 unless persisted?
+
+      current_primary = primary_state_value
+      return 0 unless current_primary
+
+      metrics = state_metrics_hash[current_primary.to_s] || {}
+      entered_at = metrics["entered_at"]
+
+      return 0 unless entered_at
+
+      base_duration = metrics["duration"] || 0
+      time_since_entry = Time.now - Time.parse(entered_at)
+      base_duration + time_since_entry
+    end
+
+    private
+
+    def primary_state_changed?
+      send("#{primary_state}_changed?")
+    end
+
+    def micro_state_changed?
+      send("#{micro_state}_changed?")
+    end
+
+    def primary_state_was
+      send("#{primary_state}_was")
+    end
+
+    def micro_state_was
+      send("#{micro_state}_was")
+    end
+  end
+end
+

data/lib/hybrid_state_model/query_methods.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module HybridStateModel
+  module QueryMethods
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def in_primary(*states)
+        field = state_machine.primary_field
+        where(field => states.map(&:to_sym))
+      end
+
+      def in_micro(*states)
+        field = state_machine.micro_field
+        where(field => states.map(&:to_sym))
+      end
+
+      def with_primary_and_micro(primary:, micro:)
+        in_primary(primary).in_micro(micro)
+      end
+
+      def without_micro
+        field = state_machine.micro_field
+        where(field => nil)
+      end
+
+      def with_micro
+        field = state_machine.micro_field
+        where.not(field => nil)
+      end
+    end
+  end
+end
+

data/lib/hybrid_state_model/state_machine.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module HybridStateModel
+  class StateMachine
+    attr_reader :model_class, :primary_field, :micro_field, :primary_states, :micro_states,
+                :state_mappings, :callbacks, :auto_reset_micro
+
+    def initialize(model_class)
+      @model_class = model_class
+      @primary_states = []
+      @micro_states = []
+      @state_mappings = {}
+      @callbacks = {
+        before_primary_transition: {},
+        after_primary_transition: {},
+        before_micro_transition: {},
+        after_micro_transition: {}
+      }
+      @auto_reset_micro = false
+    end
+
+    def primary(field_name, states)
+      @primary_field = field_name.to_sym
+      @primary_states = states.map(&:to_sym)
+    end
+
+    def micro(field_name, states)
+      @micro_field = field_name.to_sym
+      @micro_states = states.map(&:to_sym)
+    end
+
+    def map(primary_state:, micro_states:)
+      primary_key = primary_state.to_sym
+      micro_list = Array(micro_states).map(&:to_sym)
+      @state_mappings[primary_key] = micro_list
+    end
+
+    def before_primary_transition(states, &block)
+      Array(states).each do |state|
+        @callbacks[:before_primary_transition][state.to_sym] ||= []
+        @callbacks[:before_primary_transition][state.to_sym] << block
+      end
+    end
+
+    def after_primary_transition(states, &block)
+      Array(states).each do |state|
+        @callbacks[:after_primary_transition][state.to_sym] ||= []
+        @callbacks[:after_primary_transition][state.to_sym] << block
+      end
+    end
+
+    def before_micro_transition(states, &block)
+      Array(states).each do |state|
+        @callbacks[:before_micro_transition][state.to_sym] ||= []
+        @callbacks[:before_micro_transition][state.to_sym] << block
+      end
+    end
+
+    def after_micro_transition(states, &block)
+      Array(states).each do |state|
+        @callbacks[:after_micro_transition][state.to_sym] ||= []
+        @callbacks[:after_micro_transition][state.to_sym] << block
+      end
+    end
+
+    def when_primary_changes(reset_micro: false)
+      @auto_reset_micro = reset_micro
+    end
+
+    def setup!
+      raise Error, "Primary state field must be defined" unless @primary_field
+      raise Error, "Micro state field must be defined" unless @micro_field
+      raise Error, "Primary states must be defined" if @primary_states.empty?
+
+      @model_class.include(Core)
+      @model_class.include(TransitionMethods)
+      @model_class.include(QueryMethods)
+      @model_class.include(Metrics)
+
+      setup_validations
+      setup_callbacks
+    end
+
+    def valid_primary_state?(state)
+      @primary_states.include?(state.to_sym)
+    end
+
+    def valid_micro_state?(micro_state, primary_state)
+      return true if micro_state.nil?
+
+      primary_key = primary_state.to_sym
+      allowed_micros = @state_mappings[primary_key]
+
+      return true if allowed_micros.nil? || allowed_micros.empty?
+
+      allowed_micros.include?(micro_state.to_sym)
+    end
+
+    def can_transition_to_primary?(record, new_state)
+      return false unless valid_primary_state?(new_state)
+
+      # Check callbacks
+      callbacks = @callbacks[:before_primary_transition][new_state.to_sym] || []
+      callbacks.all? { |cb| record.instance_exec(&cb) != false }
+    end
+
+    def can_transition_to_micro?(record, new_micro_state)
+      return false if new_micro_state.nil?
+
+      current_primary = record.send(@primary_field)
+      return false unless valid_micro_state?(new_micro_state, current_primary)
+
+      # Check callbacks
+      callbacks = @callbacks[:before_micro_transition][new_micro_state.to_sym] || []
+      callbacks.all? { |cb| record.instance_exec(&cb) != false }
+    end
+
+    private
+
+    def setup_validations
+      @model_class.validate :validate_hybrid_state
+
+      @model_class.define_method(:validate_hybrid_state) do
+        current_primary = send(state_machine.primary_field)
+        current_micro = send(state_machine.micro_field)
+
+        unless state_machine.valid_primary_state?(current_primary)
+          errors.add(state_machine.primary_field, "is not a valid primary state")
+        end
+
+        unless state_machine.valid_micro_state?(current_micro, current_primary)
+          errors.add(state_machine.micro_field, "is not valid for primary state #{current_primary}")
+        end
+      end
+    end
+
+    def setup_callbacks
+      @model_class.before_save :track_state_changes
+      @model_class.after_save :record_state_metrics
+    end
+  end
+end
+

data/lib/hybrid_state_model/transition_methods.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module HybridStateModel
+  module TransitionMethods
+    def promote!(new_primary_state, options = {})
+      new_state = new_primary_state.to_sym
+
+      unless can_transition_to_primary?(new_state)
+        raise InvalidTransitionError, "Cannot transition to primary state: #{new_state}"
+      end
+
+      old_primary = primary_state_value
+      old_micro = micro_state_value
+
+      # Run before callbacks
+      run_callbacks(:before_primary_transition, new_state)
+
+      # Update primary state
+      send("#{primary_state}=", new_state)
+
+      # Reset micro state if configured or if new state doesn't allow current micro
+      if state_machine.auto_reset_micro || !valid_micro_state?(old_micro, new_state)
+        send("#{micro_state}=", nil) unless options[:keep_micro]
+      end
+
+      # Save if not already in a transaction
+      save! unless options[:skip_save]
+
+      # Run after callbacks
+      run_callbacks(:after_primary_transition, new_state)
+
+      self
+    end
+
+    def advance!(new_micro_state, options = {})
+      new_state = new_micro_state.to_sym
+
+      unless can_transition_to_micro?(new_state)
+        raise InvalidTransitionError, "Cannot transition to micro state: #{new_state}"
+      end
+
+      # Run before callbacks
+      run_callbacks(:before_micro_transition, new_state)
+
+      # Update micro state
+      send("#{micro_state}=", new_state)
+
+      # Save if not already in a transaction
+      save! unless options[:skip_save]
+
+      # Run after callbacks
+      run_callbacks(:after_micro_transition, new_state)
+
+      self
+    end
+
+    def reset_micro!(options = {})
+      send("#{micro_state}=", nil)
+      save! unless options[:skip_save]
+      self
+    end
+
+    def transition!(primary: nil, micro: nil, options = {})
+      if primary && primary != primary_state_value
+        promote!(primary, options.merge(skip_save: true))
+      end
+
+      if micro && micro != micro_state_value
+        advance!(micro, options)
+      elsif primary && !micro
+        save! unless options[:skip_save]
+      end
+
+      self
+    end
+
+    private
+
+    def run_callbacks(callback_type, state)
+      callbacks = state_machine.callbacks[callback_type][state] || []
+      callbacks.each { |cb| instance_exec(&cb) }
+    end
+  end
+end
+

data/lib/hybrid_state_model/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module HybridStateModel
+  VERSION = "0.1.0"
+end
+

data/lib/hybrid_state_model.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "hybrid_state_model/version"
+require_relative "hybrid_state_model/core"
+require_relative "hybrid_state_model/state_machine"
+require_relative "hybrid_state_model/query_methods"
+require_relative "hybrid_state_model/metrics"
+require_relative "hybrid_state_model/transition_methods"
+
+module HybridStateModel
+  class Error < StandardError; end
+  class InvalidTransitionError < Error; end
+  class InvalidStateError < Error; end
+  class InvalidMicroStateError < Error; end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def hybrid_state(&block)
+      @state_machine = StateMachine.new(self)
+      @state_machine.instance_eval(&block)
+      @state_machine.setup!
+    end
+
+    def state_machine
+      @state_machine
+    end
+  end
+end
+

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: hybrid-state-model
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Your Name
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-11-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: |
+  hybrid-state-model introduces a revolutionary two-layer state system:
+  Primary State (high-level lifecycle) and Secondary Micro-State (small steps within primary state).
+  Perfect for complex workflows that are too complex for flat state machines but don't need full orchestration.
+email:
+- your.email@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/order_example.rb
+- hybrid-state-model.gemspec
+- lib/hybrid_state_model.rb
+- lib/hybrid_state_model/core.rb
+- lib/hybrid_state_model/metrics.rb
+- lib/hybrid_state_model/query_methods.rb
+- lib/hybrid_state_model/state_machine.rb
+- lib/hybrid_state_model/transition_methods.rb
+- lib/hybrid_state_model/version.rb
+homepage: https://github.com/afshmini/hybrid-state-model
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/afshmini/hybrid-state-model
+  source_code_uri: https://github.com/afshmini/hybrid-state-model
+  changelog_uri: https://github.com/afshmini/hybrid-state-model/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.20
+signing_key: 
+specification_version: 4
+summary: A two-layer hierarchical state system for Ruby models
+test_files: []