pricing_plans 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99983bea54e570eebe0d01fecb11245816a95ed60eb7cc87a61756009764817f
-  data.tar.gz: 388d3c8b0791cf5388dda9d670a21fd53613105cefcf861c2769667f9f15fab1
+  metadata.gz: fee743f485f98161652b725ca25882ccdd0066500b4612d8df6cf023d22552d8
+  data.tar.gz: 61654ab323c68cde37eb9a258dc8ac3636d43e7abcae6407484a38b986342333
 SHA512:
-  metadata.gz: f99451ddc7aaba6ea9cf5bebf81395ee88383cb5a27cd2efb491ae78a711d99115f4cb5c1fade02aaa9d8cc6b09afcefe96abc8e3f00cf772d4e797b66a13424
-  data.tar.gz: bd14a7080334f2e6aeb215739d33ac3d91f97803a706dfcd83c8053b185ba36fd7797804e4a41a10500946acb00667dfabb6536fa3e184bbac41923e3adef375
+  metadata.gz: 88408758acf45aabfb9281281b31d069aeb1db85cc3bccb96f31768f2f035fc6a5e27fab9405f15525e7d521fe32381a53adbf9a8802c8cad8dc002c8f21dc3b
+  data.tar.gz: ae1ddb7ace1f67c1d5ac9213c69fe3b14a52944f8b4beb90b616463e90b8377de1d2a135920841f96a81cc1bbeb097144ca535afea6f5aaff33db9b185fdc890

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [0.4.0] - 2026-03-19
+
+- **Add plan provenance helpers**: `current_pricing_plan_resolution`, `current_pricing_plan_source`, and `PlanResolver.resolution_for(plan_owner)` now expose whether the effective plan comes from a manual assignment, a Pay subscription, or the default plan
+- **Preserve underlying billing context**: resolution objects include the current subscription when present, even when a manual assignment overrides it for entitlements
+- **Clarify effective plan vs billing state**: docs now explicitly distinguish the effective pricing plan from Pay/Stripe subscription status
+
+## [0.3.2] - 2026-02-25
+
+- **Fix stale grace warnings after plan upgrades**: Grace/blocked flags now auto-clear when usage drops below limit (self-healing state)
+- **Fix grace triggering at exact limit**: `grace_then_block` now uses `>` (over limit) not `>=` (at limit)
+- **Add lazy grace creation**: Grace starts on-demand when checking status, even if callbacks were bypassed
+- **Add `ExceededStateUtils` module**: DRY extraction for shared exceeded/blocked logic
+
 ## [0.3.1] - 2026-02-16
 
 - **Add `has_plan_assignment?` helper**: Check if a plan owner has a manual assignment without full plan resolution

data/README.md

@@ -165,6 +165,7 @@ The `pricing_plans` gem needs three new models in the schema in order to work: `
 - `PricingPlans::Assignment` allow manual plan overrides independent of billing system (or before you wire up Stripe/Pay). Great for admin toggles, trials, demos.
   - What: The arbitrary `plan_key` and a `source` label (default "manual"). Unique per plan_owner.
   - How it's used: `PlanResolver` checks manual assignment → Pay → default plan. Manual assignments (admin overrides) take precedence over subscription-based plans. You can call `assign_pricing_plan!` and `remove_pricing_plan!` on the plan_owner.
+  - Provenance helpers: `current_pricing_plan_source` tells you whether the effective plan came from `:assignment`, `:subscription`, or `:default`, and `current_pricing_plan_resolution` exposes the assignment and current subscription objects when you need both entitlement and billing context.
 
 - `PricingPlans::EnforcementState` tracks per-plan_owner per-limit enforcement state for persistent caps and per-period allowances (grace/warnings/block state) in a race-safe way.
   - What: `exceeded_at`, `blocked_at`, last warning info, and a small JSON `data` column where we persist plan-derived parameters like grace period seconds.
@@ -180,10 +181,14 @@ Enforcing pricing plans is one of those boring plumbing problems that look easy
 
 - Safe under load: we use row locks and retries when setting grace/blocked/warning state, and we avoid firing the same event twice. See [grace_manager.rb](lib/pricing_plans/grace_manager.rb).
 
+- Self-healing state: when usage drops below the limit (e.g., user deletes resources, upgrades plan, or reduces usage), stale exceeded/blocked flags are automatically cleared. Methods like `grace_active?` and `should_block?` will clear outdated enforcement state as a side effect. This prevents users from remaining incorrectly flagged after remediation.
+
 - Accurate counting: persistent limits count live current rows (using `COUNT(*)`, make sure to index your foreign keys to make it fast at scale); per‑period limits record usage for the current window only. You can filter what counts with `count_scope` (Symbol/Hash/Proc/Array), and plan settings override model defaults. See [limitable.rb](lib/pricing_plans/limitable.rb) and [limit_checker.rb](lib/pricing_plans/limit_checker.rb).
 
 - Clear rules: default is to block when you hit the cap; grace periods are opt‑in. In status/UI, 0 of 0 isn’t shown as blocked. See [plan.rb](lib/pricing_plans/plan.rb), [grace_manager.rb](lib/pricing_plans/grace_manager.rb), and [view_helpers.rb](lib/pricing_plans/view_helpers.rb).
 
+- Semantic enforcement: for `grace_then_block`, grace periods start when usage goes *over* the limit (e.g., 6/5), not when it *reaches* the limit (5/5). This allows users to use their full allocation before grace begins. For `block_usage`, blocking occurs at or over the limit (e.g., at 5/5, the next creation is blocked).
+
 - Simple controllers: one‑liners to guard actions, predictable redirect order (per‑call → per‑controller → global → pricing_path), and an optional central handler. See [controller_guards.rb](lib/pricing_plans/controller_guards.rb).
 
 - Billing‑aware periods: supports billing cycle (when Pay is present), calendar month/week/day, custom time windows, and durations. See [period_calculator.rb](lib/pricing_plans/period_calculator.rb).

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/pricing_plans",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

data/docs/03-model-helpers.md

@@ -295,10 +295,32 @@ You can also use the top-level equivalents if you prefer: `PricingPlans.severity
 You can also check and override the current pricing plan for any user, which comes handy as an admin:
 ```ruby
 user.current_pricing_plan                    # => PricingPlans::Plan
+user.current_pricing_plan_source             # => :assignment, :subscription, :default
+user.current_pricing_plan_resolution         # => PricingPlans::PlanResolution
 user.assign_pricing_plan!(:pro)              # manual assignment override
 user.remove_pricing_plan!                    # remove manual override (fallback to default)
 ```
 
+**Performance note:** Each call to `current_pricing_plan`, `current_pricing_plan_source`, or `current_pricing_plan_resolution` performs a fresh database lookup. If you need both the plan and its provenance, call `current_pricing_plan_resolution` once and read both values from that object — this avoids duplicate queries.
+
+If you need the full provenance, use the resolution object:
+
+```ruby
+resolution = user.current_pricing_plan_resolution
+
+resolution.plan.key                          # => :enterprise
+resolution.source                            # => :assignment
+resolution.assignment                        # => PricingPlans::Assignment | nil
+resolution.assignment_source                 # => "admin" | "manual" | nil
+resolution.subscription                      # => Pay subscription | nil
+```
+
+This distinction matters: the **effective pricing plan** is what controls entitlements and limits inside your app. The **Pay/Stripe subscription state** is billing-facing. A manual assignment may intentionally override the subscription-backed plan while still leaving the underlying subscription present for billing operations.
+
+**Edge case:** `source` can be `:default` even when `subscription` is non-nil. This happens when a Pay subscription exists but its `processor_plan` (Stripe price ID) doesn't map to any plan in your registry. The subscription is preserved for billing context, but the effective plan falls back to your configured default.
+
+`resolution.to_h` is handy for inspection and tests, but it preserves the raw `plan`, `assignment`, and `subscription` objects. If you need a JSON-safe payload, build one explicitly from the scalar fields you care about.
+
 ### Misc
 
 ```ruby
@@ -311,7 +333,8 @@ And finally, you get very thin convenient wrappers if you're using the `pay` gem
 ```ruby
 # Pay (Stripe) convenience (returns false/nil when Pay is absent)
 # Note: this is billing-facing state, distinct from our in-app
-# enforcement grace which is tracked per-limit.
+# enforcement grace which is tracked per-limit, and distinct from
+# the effective plan resolved by current_pricing_plan.
 user.pay_subscription_active?                # => true/false
 user.pay_on_trial?                           # => true/false
 user.pay_on_grace_period?                    # => true/false

data/lib/pricing_plans/callbacks.rb

@@ -106,17 +106,24 @@ module PricingPlans
       return if limit_config[:to] == :unlimited
 
       limit_amount = limit_config[:to].to_i
-      return unless current_usage >= limit_amount
+      after_limit = limit_config[:after_limit]
 
-      case limit_config[:after_limit]
+      case after_limit
       when :just_warn
+        return unless current_usage >= limit_amount
+
         # Just emit warning, don't track grace/block
         check_and_emit_warnings!(plan_owner, limit_key, current_usage, limit_amount)
       when :block_usage
+        return unless current_usage >= limit_amount
+
         # Do NOT mark as blocked here - this callback runs after SUCCESSFUL creation.
         # Block events are emitted from validation when creation is actually blocked.
         nil
       when :grace_then_block
+        # Grace semantics are for over-limit usage, not exact-at-limit.
+        return unless current_usage > limit_amount
+
         # Start grace period if not already in grace/blocked
         unless GraceManager.grace_active?(plan_owner, limit_key) || GraceManager.should_block?(plan_owner, limit_key)
           GraceManager.mark_exceeded!(plan_owner, limit_key, grace_period: limit_config[:grace])

data/lib/pricing_plans/exceeded_state_utils.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Shared utilities for checking and managing exceeded state.
+  #
+  # This module provides common logic for determining whether usage has exceeded
+  # limits and for clearing stale exceeded flags. It is included by both
+  # GraceManager (class methods) and StatusContext (instance methods) to ensure
+  # consistent behavior.
+  #
+  # NOTE: Methods that modify state (`clear_exceeded_flags!`) are intentionally
+  # included here. The design decision is that grace/block checks should be
+  # "self-healing" - if usage drops below the limit, stale exceeded flags are
+  # automatically cleared. This prevents situations where users remain incorrectly
+  # flagged as exceeded after deleting resources or after plan upgrades.
+  module ExceededStateUtils
+    # Determine if usage has exceeded the limit based on the after_limit policy.
+    #
+    # For :grace_then_block, exceeded means strictly OVER the limit (>).
+    # For :block_usage and :just_warn, exceeded means AT or over the limit (>=).
+    #
+    # This distinction exists because:
+    # - :block_usage blocks creation of the Nth item (at limit = blocked)
+    # - :grace_then_block allows the Nth item, only starting grace when OVER
+    #
+    # @param current_usage [Integer] Current usage count
+    # @param limit_amount [Integer, Symbol] The configured limit (may be :unlimited)
+    # @param after_limit [Symbol] The enforcement policy (:block_usage, :grace_then_block, :just_warn)
+    # @return [Boolean] true if usage is considered exceeded for this policy
+    def exceeded_now?(current_usage, limit_amount, after_limit:)
+      # 0-of-0 is a special case: not considered exceeded for UX purposes
+      return false if limit_amount.to_i.zero? && current_usage.to_i.zero?
+
+      if after_limit == :grace_then_block
+        current_usage > limit_amount.to_i
+      else
+        current_usage >= limit_amount.to_i
+      end
+    end
+
+    # Clear exceeded and blocked flags from an enforcement state record.
+    #
+    # This is called when usage drops below the limit to "heal" stale state.
+    # Uses update_columns for efficiency (skips validations/callbacks).
+    #
+    # @param state [EnforcementState] The state record to clear
+    # @return [EnforcementState, nil] The updated state, or nil if no updates needed
+    def clear_exceeded_flags!(state)
+      return unless state
+
+      updates = {}
+      updates[:exceeded_at] = nil if state.exceeded_at.present?
+      updates[:blocked_at] = nil if state.blocked_at.present?
+      return state if updates.empty?
+
+      updates[:updated_at] = Time.current
+      state.update_columns(updates)
+      state
+    end
+  end
+end

data/lib/pricing_plans/grace_manager.rb

@@ -3,6 +3,7 @@
 module PricingPlans
   class GraceManager
     class << self
+      include ExceededStateUtils
       def mark_exceeded!(plan_owner, limit_key, grace_period: nil)
         with_lock(plan_owner, limit_key) do |state|
           # Ensure state is for the current window for per-period limits
@@ -36,6 +37,14 @@ module PricingPlans
       def grace_active?(plan_owner, limit_key)
         state = fresh_state_or_nil(plan_owner, limit_key)
         return false unless state&.exceeded?
+
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        unless currently_exceeded?(plan_owner, limit_key, limit_config)
+          clear_exceeded_flags!(state)
+          return false
+        end
+
         !state.grace_expired?
       end
 
@@ -51,11 +60,16 @@ module PricingPlans
         limit_amount = limit_config[:to]
         return false if limit_amount == :unlimited
         current_usage = LimitChecker.current_usage_for(plan_owner, limit_key, limit_config)
-        exceeded = current_usage >= limit_amount.to_i
-        # Treat 0-of-0 as not blocked for UX/severity/status purposes
-        exceeded = false if limit_amount.to_i.zero? && current_usage.to_i.zero?
+        exceeded = exceeded_now?(current_usage, limit_amount, after_limit: after_limit)
 
-        return exceeded if after_limit == :block_usage
+        unless exceeded
+          if (state = fresh_state_or_nil(plan_owner, limit_key))
+            clear_exceeded_flags!(state)
+          end
+          return false
+        end
+
+        return true if after_limit == :block_usage
 
         # For :grace_then_block, check if grace period expired
         state = fresh_state_or_nil(plan_owner, limit_key)
@@ -119,7 +133,7 @@ module PricingPlans
       end
 
       def grace_ends_at(plan_owner, limit_key)
-        state = find_state(plan_owner, limit_key)
+        state = fresh_state_or_nil(plan_owner, limit_key)
         state&.grace_ends_at
       end
 
@@ -158,6 +172,17 @@ module PricingPlans
         EnforcementState.find_by(plan_owner: plan_owner, limit_key: limit_key.to_s)
       end
 
+      def currently_exceeded?(plan_owner, limit_key, limit_config = nil)
+        limit_config ||= PlanResolver.effective_plan_for(plan_owner)&.limit_for(limit_key)
+        return false unless limit_config
+
+        limit_amount = limit_config[:to]
+        return false if limit_amount == :unlimited
+
+        current_usage = LimitChecker.current_usage_for(plan_owner, limit_key, limit_config)
+        exceeded_now?(current_usage, limit_amount, after_limit: limit_config[:after_limit])
+      end
+
       # Returns nil if state is stale for the current period window for per-period limits
       def fresh_state_or_nil(plan_owner, limit_key)
         state = find_state(plan_owner, limit_key)

data/lib/pricing_plans/pay_support.rb

@@ -15,7 +15,8 @@ module PricingPlans
     def subscription_active_for?(plan_owner)
       return false unless plan_owner
 
-      log_debug "[PricingPlans::PaySupport] subscription_active_for? called for #{plan_owner.class.name}##{plan_owner.id}"
+      owner_id = plan_owner.respond_to?(:id) ? plan_owner.id : "N/A"
+      log_debug "[PricingPlans::PaySupport] subscription_active_for? called for #{plan_owner.class.name}##{owner_id}"
 
       # Prefer Pay's official API on the payment_processor
       if plan_owner.respond_to?(:payment_processor) && (pp = plan_owner.payment_processor)
@@ -66,7 +67,8 @@ module PricingPlans
     def current_subscription_for(plan_owner)
       return nil unless pay_available?
 
-      log_debug "[PricingPlans::PaySupport] current_subscription_for called for #{plan_owner.class.name}##{plan_owner.id}"
+      owner_id = plan_owner.respond_to?(:id) ? plan_owner.id : "N/A"
+      log_debug "[PricingPlans::PaySupport] current_subscription_for called for #{plan_owner.class.name}##{owner_id}"
 
       # Prefer Pay's payment_processor API
       if plan_owner.respond_to?(:payment_processor) && (pp = plan_owner.payment_processor)

data/lib/pricing_plans/plan_owner.rb

@@ -198,6 +198,14 @@ module PricingPlans
       PlanResolver.effective_plan_for(self)
     end
 
+    def current_pricing_plan_resolution
+      PlanResolver.resolution_for(self)
+    end
+
+    def current_pricing_plan_source
+      current_pricing_plan_resolution.source
+    end
+
     def on_free_plan?
       plan = current_pricing_plan || PricingPlans::Registry.default_plan
       plan&.free? || false

data/lib/pricing_plans/plan_resolution.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class PlanResolution < Struct.new(:plan, :source, :assignment, :subscription, keyword_init: true)
+    SOURCES = [:assignment, :subscription, :default].freeze
+
+    def initialize(**attributes)
+      super
+
+      unless SOURCES.include?(source)
+        raise ArgumentError, "Invalid source: #{source.inspect}. Must be one of: #{SOURCES.inspect}"
+      end
+
+      freeze
+    end
+
+    def assignment?
+      source == :assignment
+    end
+
+    def subscription?
+      source == :subscription
+    end
+
+    def default?
+      source == :default
+    end
+
+    def plan_key
+      plan&.key
+    end
+
+    def assignment_source
+      assignment&.source
+    end
+
+    # Extends Struct#to_h with derived fields.
+    # Note: this preserves the raw plan / assignment / subscription objects.
+    def to_h
+      super.merge(
+        plan_key: plan_key,
+        assignment_source: assignment_source
+      )
+    end
+  end
+end

data/lib/pricing_plans/plan_resolver.rb

@@ -8,43 +8,52 @@ module PricingPlans
       end
 
       def effective_plan_for(plan_owner)
-        log_debug "[PricingPlans::PlanResolver] effective_plan_for called for #{plan_owner.class.name}##{plan_owner.respond_to?(:id) ? plan_owner.id : 'N/A'}"
+        resolution_for(plan_owner).plan
+      end
 
-        # 1. Check manual assignment FIRST (admin overrides take precedence)
-        log_debug "[PricingPlans::PlanResolver] Checking for manual assignment..."
-        if plan_owner.respond_to?(:id)
-          assignment = Assignment.find_by(
-            plan_owner_type: plan_owner.class.name,
-            plan_owner_id: plan_owner.id
+      def plan_key_for(plan_owner)
+        resolution_for(plan_owner).plan_key
+      end
+
+      def resolution_for(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] resolution_for called for #{plan_owner.class.name}##{plan_owner.respond_to?(:id) ? plan_owner.id : 'N/A'}"
+
+        assignment = assignment_for(plan_owner)
+        subscription = current_subscription_for(plan_owner)
+
+        if assignment
+          log_debug "[PricingPlans::PlanResolver] Returning assignment-backed resolution: #{assignment.plan_key}"
+          return PlanResolution.new(
+            plan: Registry.plan(assignment.plan_key),
+            source: :assignment,
+            assignment: assignment,
+            subscription: subscription
           )
-          if assignment
-            log_debug "[PricingPlans::PlanResolver] Found manual assignment: #{assignment.plan_key}"
-            return Registry.plan(assignment.plan_key)
-          else
-            log_debug "[PricingPlans::PlanResolver] No manual assignment found"
-          end
         end
 
-        # 2. Check Pay subscription status
-        pay_available = PaySupport.pay_available?
-        log_debug "[PricingPlans::PlanResolver] PaySupport.pay_available? = #{pay_available}"
-        log_debug "[PricingPlans::PlanResolver] defined?(Pay) = #{defined?(Pay)}"
-
-        if pay_available
-          log_debug "[PricingPlans::PlanResolver] Calling resolve_plan_from_pay..."
-          plan_from_pay = resolve_plan_from_pay(plan_owner)
-          log_debug "[PricingPlans::PlanResolver] resolve_plan_from_pay returned: #{plan_from_pay ? plan_from_pay.key : 'nil'}"
-          return plan_from_pay if plan_from_pay
+        if subscription
+          processor_plan = subscription.processor_plan
+          log_debug "[PricingPlans::PlanResolver] resolution_for subscription processor_plan = #{processor_plan.inspect}"
+
+          if processor_plan && (plan = plan_from_processor_plan(processor_plan))
+            log_debug "[PricingPlans::PlanResolver] Returning subscription-backed resolution: #{plan.key}"
+            return PlanResolution.new(
+              plan: plan,
+              source: :subscription,
+              assignment: nil,
+              subscription: subscription
+            )
+          end
         end
 
-        # 3. Fall back to default plan
         default = Registry.default_plan
-        log_debug "[PricingPlans::PlanResolver] Returning default plan: #{default ? default.key : 'nil'}"
-        default
-      end
-
-      def plan_key_for(plan_owner)
-        effective_plan_for(plan_owner)&.key
+        log_debug "[PricingPlans::PlanResolver] Returning default-backed resolution: #{default ? default.key : 'nil'}"
+        PlanResolution.new(
+          plan: default,
+          source: :default,
+          assignment: nil,
+          subscription: subscription
+        )
       end
 
       def assign_plan_manually!(plan_owner, plan_key, source: "manual")
@@ -62,46 +71,38 @@ module PricingPlans
         PaySupport.pay_available?
       end
 
-      def resolve_plan_from_pay(plan_owner)
-        log_debug "[PricingPlans::PlanResolver] resolve_plan_from_pay: checking if plan_owner has payment_processor or Pay methods..."
-
-        # Check if plan_owner has payment_processor (preferred) or Pay methods directly (fallback)
-        has_payment_processor = plan_owner.respond_to?(:payment_processor)
-        has_pay_methods = plan_owner.respond_to?(:subscribed?) ||
-                          plan_owner.respond_to?(:on_trial?) ||
-                          plan_owner.respond_to?(:on_grace_period?) ||
-                          plan_owner.respond_to?(:subscriptions)
+      def assignment_for(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] Checking for manual assignment..."
+        return nil unless plan_owner.respond_to?(:id)
 
-        log_debug "[PricingPlans::PlanResolver] has_payment_processor? #{has_payment_processor}"
-        log_debug "[PricingPlans::PlanResolver] has_pay_methods? #{has_pay_methods}"
+        assignment = Assignment.find_by(
+          plan_owner_type: plan_owner.class.name,
+          plan_owner_id: plan_owner.id
+        )
 
-        # PaySupport will handle both payment_processor and direct Pay methods
-        return nil unless has_payment_processor || has_pay_methods
+        if assignment
+          log_debug "[PricingPlans::PlanResolver] Found manual assignment: #{assignment.plan_key}"
+        else
+          log_debug "[PricingPlans::PlanResolver] No manual assignment found"
+        end
 
-        # Check if plan_owner has active subscription, trial, or grace period
-        log_debug "[PricingPlans::PlanResolver] Calling PaySupport.subscription_active_for?..."
-        is_active = PaySupport.subscription_active_for?(plan_owner)
-        log_debug "[PricingPlans::PlanResolver] subscription_active_for? returned: #{is_active}"
+        assignment
+      end
 
-        if is_active
-          log_debug "[PricingPlans::PlanResolver] Calling PaySupport.current_subscription_for..."
-          subscription = PaySupport.current_subscription_for(plan_owner)
-          log_debug "[PricingPlans::PlanResolver] current_subscription_for returned: #{subscription ? subscription.class.name : 'nil'}"
-          return nil unless subscription
+      def current_subscription_for(plan_owner)
+        return nil unless plan_owner
 
-          # Map processor plan to our plan
-          processor_plan = subscription.processor_plan
-          log_debug "[PricingPlans::PlanResolver] subscription.processor_plan = #{processor_plan.inspect}"
+        pay_available = pay_available?
+        log_debug "[PricingPlans::PlanResolver] PaySupport.pay_available? = #{pay_available}"
 
-          if processor_plan
-            matched_plan = plan_from_processor_plan(processor_plan)
-            log_debug "[PricingPlans::PlanResolver] plan_from_processor_plan returned: #{matched_plan ? matched_plan.key : 'nil'}"
-            return matched_plan
-          end
-        end
+        return nil unless pay_available
 
-        log_debug "[PricingPlans::PlanResolver] resolve_plan_from_pay returning nil"
-        nil
+        # This intentionally delegates the active/trial/grace filtering contract
+        # to PaySupport.current_subscription_for so resolution_for can preserve
+        # the same billing context wherever it is called.
+        subscription = PaySupport.current_subscription_for(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] current_subscription_for returned: #{subscription ? subscription.class.name : 'nil'}"
+        subscription
       end
 
       def plan_from_processor_plan(processor_plan)

data/lib/pricing_plans/status_context.rb

@@ -7,6 +7,8 @@ module PricingPlans
   #
   # Thread-safe by design: each call to status() gets its own context instance.
   class StatusContext
+    include ExceededStateUtils
+
     attr_reader :plan_owner
 
     def initialize(plan_owner)
@@ -67,7 +69,26 @@ module PricingPlans
       return @grace_active_cache[key] if @grace_active_cache.key?(key)
 
       state = fresh_enforcement_state(limit_key)
-      return @grace_active_cache[key] = false unless state&.exceeded?
+
+      # If no state exists but we're over limit for grace_then_block, lazily create grace
+      unless state&.exceeded?
+        if should_lazily_start_grace?(limit_key)
+          limit_config = limit_config_for(limit_key)
+          GraceManager.mark_exceeded!(@plan_owner, limit_key, grace_period: limit_config[:grace])
+          # Clear caches to get fresh state
+          @fresh_enforcement_state_cache&.delete(key)
+          @enforcement_state_cache&.delete(key)
+          state = fresh_enforcement_state(limit_key)
+        else
+          return @grace_active_cache[key] = false
+        end
+      end
+
+      unless currently_exceeded?(limit_key)
+        clear_exceeded_flags!(state)
+        return @grace_active_cache[key] = false
+      end
+
       @grace_active_cache[key] = !state.grace_expired?
     end
 
@@ -77,7 +98,10 @@ module PricingPlans
       return @grace_ends_at_cache[key] if @grace_ends_at_cache.key?(key)
 
       state = fresh_enforcement_state(limit_key)
-      @grace_ends_at_cache[key] = state&.grace_ends_at
+      return @grace_ends_at_cache[key] = nil unless state&.exceeded?
+      return @grace_ends_at_cache[key] = nil unless grace_active?(limit_key)
+
+      @grace_ends_at_cache[key] = state.grace_ends_at
     end
 
     # Cached should block check - implemented directly to avoid GraceManager's plan resolution
@@ -95,13 +119,16 @@ module PricingPlans
       return @should_block_cache[key] = false if limit_amount == :unlimited
 
       current_usage = current_usage_for(limit_key)
-      exceeded = current_usage >= limit_amount.to_i
-      exceeded = false if limit_amount.to_i.zero? && current_usage.to_i.zero?
+      exceeded = exceeded_now?(current_usage, limit_amount, after_limit: after_limit)
 
       return @should_block_cache[key] = exceeded if after_limit == :block_usage
 
       # For :grace_then_block, check if grace period expired
-      return @should_block_cache[key] = false unless exceeded
+      unless exceeded
+        state = fresh_enforcement_state(limit_key)
+        clear_exceeded_flags!(state) if state
+        return @should_block_cache[key] = false
+      end
 
       state = fresh_enforcement_state(limit_key)
       return @should_block_cache[key] = false unless state&.exceeded?
@@ -339,5 +366,32 @@ module PricingPlans
       highest_warn = warn_thresholds.max.to_f * 100.0
       (percent >= highest_warn && highest_warn.positive?) ? :warning : :ok
     end
+
+    def currently_exceeded?(limit_key)
+      limit_config = limit_config_for(limit_key)
+      return false unless limit_config
+
+      limit_amount = limit_config[:to]
+      return false if limit_amount == :unlimited
+
+      current_usage = current_usage_for(limit_key)
+      exceeded_now?(current_usage, limit_amount, after_limit: limit_config[:after_limit])
+    end
+
+    # Check if we should lazily start grace for this limit.
+    # This handles edge cases where usage increased without triggering callbacks
+    # (e.g., status changes, bulk imports, manual DB updates).
+    def should_lazily_start_grace?(limit_key)
+      limit_config = limit_config_for(limit_key)
+      return false unless limit_config
+      return false unless limit_config[:after_limit] == :grace_then_block
+
+      limit_amount = limit_config[:to]
+      return false if limit_amount == :unlimited
+
+      current_usage = current_usage_for(limit_key)
+      current_usage > limit_amount.to_i
+    end
+
   end
 end

data/lib/pricing_plans/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PricingPlans
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/pricing_plans.rb

@@ -21,12 +21,14 @@ module PricingPlans
   autoload :Configuration, "pricing_plans/configuration"
   autoload :Registry, "pricing_plans/registry"
   autoload :Plan, "pricing_plans/plan"
+  autoload :PlanResolution, "pricing_plans/plan_resolution"
   autoload :DSL, "pricing_plans/dsl"
   autoload :IntegerRefinements, "pricing_plans/integer_refinements"
   autoload :PlanResolver, "pricing_plans/plan_resolver"
   autoload :PaySupport, "pricing_plans/pay_support"
   autoload :LimitChecker, "pricing_plans/limit_checker"
   autoload :LimitableRegistry, "pricing_plans/limit_checker"
+  autoload :ExceededStateUtils, "pricing_plans/exceeded_state_utils"
   autoload :GraceManager, "pricing_plans/grace_manager"
   autoload :Callbacks, "pricing_plans/callbacks"
   autoload :PeriodCalculator, "pricing_plans/period_calculator"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pricing_plans
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-02-16 00:00:00.000000000 Z
+date: 2026-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -70,6 +70,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- context7.json
 - docs/01-define-pricing-plans.md
 - docs/02-controller-helpers.md
 - docs/03-model-helpers.md
@@ -93,6 +94,7 @@ files:
 - lib/pricing_plans/controller_rescues.rb
 - lib/pricing_plans/dsl.rb
 - lib/pricing_plans/engine.rb
+- lib/pricing_plans/exceeded_state_utils.rb
 - lib/pricing_plans/grace_manager.rb
 - lib/pricing_plans/integer_refinements.rb
 - lib/pricing_plans/job_guards.rb
@@ -106,6 +108,7 @@ files:
 - lib/pricing_plans/period_calculator.rb
 - lib/pricing_plans/plan.rb
 - lib/pricing_plans/plan_owner.rb
+- lib/pricing_plans/plan_resolution.rb
 - lib/pricing_plans/plan_resolver.rb
 - lib/pricing_plans/price_components.rb
 - lib/pricing_plans/registry.rb