pricing_plans 0.5.0 → 0.6.0

data/lib/pricing_plans/models/assignment.rb

@@ -22,8 +22,7 @@ module PricingPlans
 
     def self.create_or_update_pricing_plan_override_for!(plan_owner, plan_key, source:)
       assignment = find_or_initialize_by(
-        plan_owner_type: plan_owner.class.name,
-        plan_owner_id: plan_owner.id
+        PlanOwnerIdentity.conditions_for(plan_owner)
       )
 
       assignment.assign_attributes(
@@ -37,8 +36,7 @@ module PricingPlans
 
     def self.clear_pricing_plan_override_for!(plan_owner)
       where(
-        plan_owner_type: plan_owner.class.name,
-        plan_owner_id: plan_owner.id
+        PlanOwnerIdentity.conditions_for(plan_owner)
       ).destroy_all
     end
 

data/lib/pricing_plans/models/feature_grant.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # A per-owner feature entitlement that overrides plan resolution: comps,
+  # beta access, sales exceptions, support remediation, or a grandfather
+  # promise that must survive cancellation. Where the `grandfather` plan DSL
+  # is cohort-level policy (config, no state), a grant is an individual,
+  # auditable exception (a row, with a reason).
+  #
+  # Grants are never deleted by the API: revoking stamps `revoked_at` so the
+  # answer to "why does this customer have this?" survives the revocation.
+  class FeatureGrant < ActiveRecord::Base
+    self.table_name = "pricing_plans_feature_grants"
+
+    belongs_to :plan_owner, polymorphic: true
+
+    validates :plan_owner, presence: true
+    validates :feature_key, presence: true
+    validates :source, presence: true
+    validate :expires_at_must_be_parseable
+
+    scope :for_feature, ->(feature_key) { where(feature_key: feature_key.to_s) }
+    scope :active, lambda {
+      where(revoked_at: nil).where("expires_at IS NULL OR expires_at > ?", Time.current)
+    }
+
+    def active?
+      revoked_at.nil? && (expires_at.nil? || expires_at > Time.current)
+    end
+
+    def revoke!(note: nil)
+      return self if revoked_at.present?
+
+      update!(revoked_at: Time.current, note: [self.note, note].compact.presence&.join(" | "))
+      self
+    end
+
+    class << self
+      # Idempotent: updates the active grant for (owner, feature) if one
+      # exists, otherwise creates it. Revoked grants stay behind as history.
+      def grant_to!(plan_owner, feature_key, source: "manual", note: nil, expires_at: nil)
+        ensure_table!
+        ensure_persisted_owner!(plan_owner)
+
+        # Serialize grant writes through the owner row. A lookup followed by
+        # create is otherwise race-prone, and a portable partial unique index
+        # cannot express "unrevoked and unexpired" consistently on every
+        # supported database.
+        with_locked_owner(plan_owner) do
+          grant = active.find_by(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s))
+          if grant
+            grant.update!(source: source.to_s, note: note, expires_at: expires_at)
+            grant
+          else
+            create!(
+              plan_owner: plan_owner,
+              feature_key: feature_key.to_s,
+              source: source.to_s,
+              note: note,
+              expires_at: expires_at
+            )
+          end
+        end
+      end
+
+      def revoke_for!(plan_owner, feature_key, note: nil)
+        ensure_table!
+        ensure_persisted_owner!(plan_owner)
+
+        with_locked_owner(plan_owner) do
+          active
+            .where(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s))
+            .map { |grant| grant.revoke!(note: note) }
+        end
+      end
+
+      def active_for?(plan_owner, feature_key)
+        return false unless table_ready?
+
+        active.where(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s)).exists?
+      end
+
+      # The grants table ships with fresh installs; apps that installed an
+      # earlier version add it with `rails generate pricing_plans:grants`.
+      # Plan-level checks (`allows` and `grandfather`) work without it, so
+      # its absence only disables per-owner grants — silently for reads,
+      # loudly for writes.
+      def table_ready?
+        table_exists?
+      rescue ActiveRecord::ActiveRecordError
+        false
+      end
+
+      private
+
+      def ensure_table!
+        return if table_ready?
+
+        raise ConfigurationError,
+              "The #{table_name} table does not exist. Run " \
+              "`rails generate pricing_plans:grants && rails db:migrate` to add it."
+      end
+
+      def owner_conditions(plan_owner)
+        PlanOwnerIdentity.conditions_for(plan_owner)
+      end
+
+      def ensure_persisted_owner!(plan_owner)
+        persisted_active_record = plan_owner.respond_to?(:persisted?) &&
+                                  plan_owner.persisted? &&
+                                  plan_owner.class.respond_to?(:base_class)
+        return if persisted_active_record
+
+        raise ArgumentError, "plan_owner must be a persisted Active Record"
+      end
+
+      def with_locked_owner(plan_owner)
+        owner_class = plan_owner.class.base_class
+
+        owner_class.transaction do
+          # Lock a fresh copy so granting a feature never reloads or rejects a
+          # caller that happens to have unrelated unsaved changes.
+          owner_class.unscoped.lock.find(plan_owner.id)
+          yield
+        end
+      end
+    end
+
+    private
+
+    def expires_at_must_be_parseable
+      raw_value = expires_at_before_type_cast
+      return if raw_value.nil? || (raw_value.is_a?(String) && raw_value.blank?)
+      return if expires_at.respond_to?(:to_time)
+
+      errors.add(:expires_at, "must be a valid time")
+    end
+  end
+end

data/lib/pricing_plans/overage_reporter.rb

@@ -10,6 +10,7 @@ module PricingPlans
       :overage,
       :grace_active,
       :grace_ends_at,
+      :grace_window,
       keyword_init: true
     )
 
@@ -37,7 +38,12 @@ module PricingPlans
             allowed: allowed,
             overage: over_by,
             grace_active: GraceManager.grace_active?(plan_owner, limit_key),
-            grace_ends_at: GraceManager.grace_ends_at(plan_owner, limit_key)
+            grace_ends_at: GraceManager.grace_ends_at(plan_owner, limit_key),
+            # The CONFIGURED window on the target plan (nil unless the limit
+            # is :grace_then_block, where alone grace is honored) — so
+            # downgrade/dunning UX can say "after a N-day grace window"
+            # without re-deriving enforcement rules.
+            grace_window: limit_config[:grace]
           )
         end.compact
       end

data/lib/pricing_plans/pay_support.rb

@@ -12,120 +12,112 @@ module PricingPlans
       puts message if PricingPlans.configuration&.debug
     end
 
+    # Whether an owner currently has a billing relationship that should keep
+    # plan entitlements. Besides Pay's active/trial/grace states, this includes
+    # past_due while the processor is retrying payment. Canceled and unpaid
+    # subscriptions remain ineligible.
     def subscription_active_for?(plan_owner)
       return false unless plan_owner
 
-      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)
-        log_debug "[PricingPlans::PaySupport] payment_processor found: #{pp.class.name}##{pp.id}"
-
-        # Check all subscriptions, not just the default-named one
-        # Note: Don't call pp.subscribed?() without a name parameter, as it defaults to
-        # checking only for subscriptions named Pay.default_product_name (usually "default")
-        if pp.respond_to?(:subscriptions)
-          subs = pp.subscriptions
-          log_debug "[PricingPlans::PaySupport] subscriptions relation: #{subs.class.name}, count: #{subs.count}"
-
-          # Force array conversion to ensure we iterate through all subscriptions
-          # Some ActiveRecord relations might not enumerate properly in boolean context
-          subs_array = subs.respond_to?(:to_a) ? subs.to_a : subs
-          log_debug "[PricingPlans::PaySupport] subscriptions array size: #{subs_array.size}"
-
-          subs_array.each_with_index do |sub, idx|
-            log_debug "[PricingPlans::PaySupport]   [#{idx}] Subscription: #{sub.class.name}##{sub.id}, name: #{sub.name rescue 'N/A'}, status: #{sub.status rescue 'N/A'}, active?: #{sub.active? rescue 'N/A'}, on_trial?: #{sub.on_trial? rescue 'N/A'}, on_grace_period?: #{sub.on_grace_period? rescue 'N/A'}"
-          end
-
-          result = subs_array.any? { |sub| (sub.respond_to?(:active?) && sub.active?) || (sub.respond_to?(:on_trial?) && sub.on_trial?) || (sub.respond_to?(:on_grace_period?) && sub.on_grace_period?) }
-          log_debug "[PricingPlans::PaySupport] subscription_active_for? returning: #{result}"
-          return result
-        else
-          log_debug "[PricingPlans::PaySupport] payment_processor does not respond to :subscriptions"
-        end
-      else
-        log_debug "[PricingPlans::PaySupport] No payment_processor found or plan_owner doesn't respond to :payment_processor"
-      end
-
-      # Fallbacks for apps that surface Pay state on the owner
-      individual_active = (plan_owner.respond_to?(:subscribed?) && plan_owner.subscribed?) ||
-                          (plan_owner.respond_to?(:on_trial?) && plan_owner.on_trial?) ||
-                          (plan_owner.respond_to?(:on_grace_period?) && plan_owner.on_grace_period?)
-      log_debug "[PricingPlans::PaySupport] Fallback individual_active: #{individual_active}"
-      return true if individual_active
+      log_debug "[PricingPlans::PaySupport] subscription_active_for? called for #{owner_label(plan_owner)}"
 
-      if plan_owner.respond_to?(:subscriptions) && (subs = plan_owner.subscriptions)
-        log_debug "[PricingPlans::PaySupport] Checking plan_owner.subscriptions fallback"
-        return subs.any? { |sub| (sub.respond_to?(:active?) && sub.active?) || (sub.respond_to?(:on_trial?) && sub.on_trial?) || (sub.respond_to?(:on_grace_period?) && sub.on_grace_period?) }
-      end
-
-      log_debug "[PricingPlans::PaySupport] subscription_active_for? returning false (no active subscription found)"
-      false
+      result = current_subscriptions_for(plan_owner).any?
+      log_debug "[PricingPlans::PaySupport] subscription_active_for? returning: #{result}"
+      result
     end
 
     def current_subscription_for(plan_owner)
-      return nil unless pay_available?
+      current_subscriptions_for(plan_owner).first
+    end
 
-      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)
-        log_debug "[PricingPlans::PaySupport] payment_processor found: #{pp.class.name}##{pp.id}"
-
-        # Check all subscriptions, not just the default-named one
-        # Note: Don't call pp.subscription() without a name parameter, as it defaults to
-        # looking for subscriptions named Pay.default_product_name (usually "default")
-        if pp.respond_to?(:subscriptions)
-          subs = pp.subscriptions
-          log_debug "[PricingPlans::PaySupport] subscriptions relation: #{subs.class.name}, count: #{subs.count}"
-
-          # Force array conversion to ensure we iterate properly
-          subs_array = subs.respond_to?(:to_a) ? subs.to_a : subs
-          log_debug "[PricingPlans::PaySupport] subscriptions array size: #{subs_array.size}"
-
-          found = subs_array.find do |sub|
-            (sub.respond_to?(:on_trial?) && sub.on_trial?) ||
-              (sub.respond_to?(:on_grace_period?) && sub.on_grace_period?) ||
-              (sub.respond_to?(:active?) && sub.active?)
-          end
-          log_debug "[PricingPlans::PaySupport] current_subscription_for found: #{found ? "#{found.class.name}##{found.id} (name: #{found.name})" : 'nil'}"
-          return found if found
-        else
-          log_debug "[PricingPlans::PaySupport] payment_processor does not respond to :subscriptions"
-        end
-      else
-        log_debug "[PricingPlans::PaySupport] No payment_processor found or plan_owner doesn't respond to :payment_processor"
+    # Returns every entitlement-bearing subscription from the canonical Pay
+    # customer. PlanResolver can then prefer one whose processor_plan appears
+    # in the registry instead of accidentally choosing an unrelated active
+    # subscription that happened to be returned first.
+    def current_subscriptions_for(plan_owner)
+      return [] unless plan_owner && pay_available?
+
+      log_debug "[PricingPlans::PaySupport] current_subscriptions_for called for #{owner_label(plan_owner)}"
+
+      processor_subscriptions = current_payment_processor_subscriptions(plan_owner)
+      return processor_subscriptions unless processor_subscriptions.empty?
+
+      subscriptions = []
+      subscriptions << plan_owner.subscription if plan_owner.respond_to?(:subscription)
+      subscriptions.concat(subscription_collection(plan_owner))
+
+      current_subscriptions_in(subscriptions.compact.uniq).tap do |current|
+        log_debug "[PricingPlans::PaySupport] found #{current.size} current owner subscription(s)"
       end
+    end
 
-      # Fallbacks for apps that surface subscriptions on the owner
-      if plan_owner.respond_to?(:subscription)
-        log_debug "[PricingPlans::PaySupport] Checking plan_owner.subscription fallback"
-        subscription = plan_owner.subscription
-        if subscription && (
-          (subscription.respond_to?(:active?) && subscription.active?) ||
-          (subscription.respond_to?(:on_trial?) && subscription.on_trial?) ||
-          (subscription.respond_to?(:on_grace_period?) && subscription.on_grace_period?)
-        )
-          log_debug "[PricingPlans::PaySupport] current_subscription_for returning fallback subscription"
-          return subscription
-        end
+    def subscription_current?(subscription)
+      return false unless subscription
+      return false if subscription.respond_to?(:ended?) && subscription.ended?
+      # Pay's Stripe adapter keeps status="past_due" while a void pause can
+      # independently become effective. Do not let the explicit past_due
+      # entitlement below revive a subscription that Pay says is currently
+      # paused. A scheduled future pause remains current through
+      # `on_grace_period?`, matching Pay's own active? semantics.
+      return false if subscription.respond_to?(:pause_active?) && subscription.pause_active?
+
+      state_predicates = %i[active? on_trial? on_grace_period? past_due?]
+      state_predicates.any? do |predicate|
+        subscription.respond_to?(predicate) && subscription.public_send(predicate)
       end
+    end
 
-      if plan_owner.respond_to?(:subscriptions) && (subs = plan_owner.subscriptions)
-        log_debug "[PricingPlans::PaySupport] Checking plan_owner.subscriptions fallback"
-        found = subs.find do |sub|
-          (sub.respond_to?(:on_trial?) && sub.on_trial?) ||
-            (sub.respond_to?(:on_grace_period?) && sub.on_grace_period?) ||
-            (sub.respond_to?(:active?) && sub.active?)
-        end
-        log_debug "[PricingPlans::PaySupport] current_subscription_for found in fallback: #{found ? "#{found.class.name}##{found.id}" : 'nil'}"
-        return found if found
+    def subscription_collection(record)
+      return [] unless record.respond_to?(:subscriptions)
+
+      subscriptions = record.subscriptions
+      return [] unless subscriptions
+
+      subscriptions.respond_to?(:to_a) ? subscriptions.to_a : Array(subscriptions)
+    end
+    private_class_method :subscription_collection
+
+    def current_payment_processor_subscriptions(plan_owner)
+      return [] unless plan_owner.respond_to?(:payment_processor)
+
+      payment_processor = payment_processor_for(plan_owner)
+      return [] unless payment_processor
+
+      current_subscriptions_in(subscription_collection(payment_processor)).tap do |subscriptions|
+        next if subscriptions.empty?
+
+        log_debug "[PricingPlans::PaySupport] found #{subscriptions.size} current payment-processor subscription(s)"
       end
+    end
+    private_class_method :current_payment_processor_subscriptions
+
+    # Pay::Attributes overrides the generated `payment_processor` association
+    # reader: when no row exists and a default processor is configured, merely
+    # calling it creates a Pay::Customer. Plan lookup is a read operation and
+    # must never acquire that side effect. Read the underlying Active Record
+    # association directly when it exists; retain the public-reader fallback
+    # for PORO integrations and older Pay-shaped adapters.
+    def payment_processor_for(plan_owner)
+      reflection =
+        if plan_owner.class.respond_to?(:reflect_on_association)
+          plan_owner.class.reflect_on_association(:payment_processor)
+        end
+
+      return plan_owner.association(:payment_processor).reader if reflection && plan_owner.respond_to?(:association)
+
+      plan_owner.payment_processor
+    end
+    private_class_method :payment_processor_for
+
+    def current_subscriptions_in(subscriptions)
+      Array(subscriptions).select { |subscription| subscription_current?(subscription) }
+    end
+    private_class_method :current_subscriptions_in
 
-      log_debug "[PricingPlans::PaySupport] current_subscription_for returning nil"
-      nil
+    def owner_label(plan_owner)
+      owner_id = plan_owner.respond_to?(:id) ? plan_owner.id : "N/A"
+      "#{plan_owner.class.name}##{owner_id}"
     end
+    private_class_method :owner_label
   end
 end

data/lib/pricing_plans/plan.rb

@@ -17,6 +17,7 @@ module PricingPlans
       @price_string = nil
       @stripe_price = nil
       @features = Set.new
+      @grandfathers = {}
       @limits = {}
       @credits_included = nil
       @meta = {}
@@ -203,20 +204,71 @@ module PricingPlans
       @features.include?(feature_key.to_sym)
     end
 
+    # Grandfathering: declare that owners whose qualifying pricing
+    # relationship predates the cutoff keep a feature the plan no longer
+    # carries. Pure config — no database state, no backfill, no rake task.
+    # The pricing history stays readable in the initializer forever:
+    #
+    #   plan :indie do
+    #     allows :api_access                # :distribution removed 2026-08-31
+    #     grandfather :distribution, subscribed_before: "2026-09-01"
+    #   end
+    #
+    # The cutoff accepts a Time, Date, or String; date-only values are read
+    # as midnight UTC. The relationship timestamp comes from the current
+    # assignment and/or same-plan subscription. Those records keep created_at
+    # across in-place plan/price changes, so this models a continuous pricing
+    # relationship rather than unavailable plan-change history. For an exact
+    # materialized cohort or a promise that must survive anything, use an
+    # explicit per-owner grant instead: `owner.grant_feature!(:distribution)`.
+    def grandfather(feature_key, subscribed_before:)
+      @grandfathers[feature_key.to_sym] = normalize_grandfather_cutoff(subscribed_before)
+    end
+
+    def grandfathered_features
+      @grandfathers.keys
+    end
+
+    def grandfather_cutoff_for(feature_key)
+      @grandfathers[feature_key.to_sym]
+    end
+
+    def grandfathers_feature?(feature_key, relationship_started_at:)
+      cutoff = grandfather_cutoff_for(feature_key)
+      return false unless cutoff && relationship_started_at
+
+      relationship_started_at < cutoff
+    end
+
     # Limit methods
     def set_limit(key, **options)
       limit_key = key.to_sym
-      @limits[limit_key] = {
+      after_limit = options.fetch(:after_limit, :block_usage)
+
+      # Grace only exists for :grace_then_block. Defaulting it onto every
+      # limit made `limit[:grace]` a lie for :block_usage/:just_warn limits
+      # (enforcement ignores it there), and downstream consumers reading the
+      # config naively would promise customers a grace window that does not
+      # exist. Explicit grace on a non-grace mode raises immediately, even if
+      # the caller supplied nil/false (truthiness must not erase intent).
+      if %i[block_usage just_warn].include?(after_limit) && options.key?(:grace)
+        raise ConfigurationError,
+              "Limit #{limit_key} cannot have grace with :#{after_limit} after_limit " \
+              "(grace only applies to :grace_then_block)"
+      end
+
+      limit = {
         key: limit_key,
         to: options[:to],
         per: options[:per],
-        after_limit: options.fetch(:after_limit, :block_usage),
-        grace: options.fetch(:grace, 7.days),
+        after_limit: after_limit,
+        grace: after_limit == :grace_then_block ? options.fetch(:grace, 7.days) : nil,
         warn_at: options.fetch(:warn_at, [0.6, 0.8, 0.95]),
         count_scope: options[:count_scope]
       }
 
-      validate_limit_options!(@limits[limit_key])
+      validate_limit_options!(limit)
+      @limits[limit_key] = limit
     end
 
     def limits(key=nil, **options)
@@ -509,9 +561,44 @@ module PricingPlans
     def validate!
       validate_limits!
       validate_pricing!
+      validate_grandfathers!
     end
 
     private
+
+    def normalize_grandfather_cutoff(value)
+      cutoff =
+        if defined?(ActiveSupport::TimeWithZone) && value.is_a?(ActiveSupport::TimeWithZone)
+          value.utc.to_time
+        else
+          case value
+          when Time then value
+          when Date, String then value.to_time(:utc)
+          else
+            raise ConfigurationError,
+                  "grandfather cutoff must be a Time, ActiveSupport::TimeWithZone, Date, or String " \
+                  "(got #{value.class})"
+          end
+        end
+
+      raise ConfigurationError, "grandfather cutoff #{value.inspect} is not a parseable time" unless cutoff.is_a?(Time)
+
+      cutoff
+    rescue ArgumentError
+      raise ConfigurationError, "grandfather cutoff #{value.inspect} is not a parseable time"
+    end
+
+    def validate_grandfathers!
+      contradiction = @grandfathers.keys & @features.to_a
+      return if contradiction.empty?
+
+      raise ConfigurationError,
+            "Plan #{key.inspect} grandfathers #{contradiction.inspect} but also allows " \
+            "them via `allows`. Grandfathering is for features the plan no longer " \
+            "carries — remove them from `allows` (everyone has them) or from " \
+            "`grandfather` (nobody needs the exception)."
+    end
+
     def validate_limits!
       @limits.each do |key, limit|
         validate_limit_options!(limit)
@@ -530,9 +617,17 @@ module PricingPlans
         raise ConfigurationError, "Limit #{limit[:key]} after_limit must be one of #{valid_after_limit.join(', ')}"
       end
 
-      # Validate grace only applies to blocking behaviors
-      if limit[:grace] && limit[:after_limit] == :just_warn
-        raise ConfigurationError, "Limit #{limit[:key]} cannot have grace with :just_warn after_limit"
+      # Grace only applies to :grace_then_block; anywhere else it would be
+      # stored but never honored, which is worse than an error.
+      if limit[:grace] && limit[:after_limit] != :grace_then_block
+        raise ConfigurationError,
+              "Limit #{limit[:key]} cannot have grace with :#{limit[:after_limit]} after_limit " \
+              "(grace only applies to :grace_then_block)"
+      end
+
+      if limit[:after_limit] == :grace_then_block && !valid_grace_window?(limit[:grace])
+        raise ConfigurationError,
+              "Limit #{limit[:key]} grace must be a positive duration of at least one second"
       end
 
       # Validate warn_at thresholds
@@ -551,6 +646,12 @@ module PricingPlans
       end
     end
 
+    def valid_grace_window?(grace)
+      grace.is_a?(Numeric) && grace.finite? && grace.to_i.positive?
+    rescue TypeError, RangeError
+      false
+    end
+
     def validate_pricing!
       # `price` and `stripe_price` are not alternatives: the number is the local
       # source of truth for display and plan comparison (resolved with no network

data/lib/pricing_plans/plan_owner.rb

@@ -158,7 +158,7 @@ module PricingPlans
           owners.join(enforcement_states)
             .on(
               enforcement_states[:plan_owner_id].eq(owners[:id])
-              .and(enforcement_states[:plan_owner_type].eq(name))
+              .and(enforcement_states[:plan_owner_type].eq(PlanOwnerIdentity.type_for(self)))
             )
             .join_sources
         )
@@ -174,7 +174,7 @@ module PricingPlans
           owners.join(enforcement_states, Arel::Nodes::OuterJoin)
             .on(
               enforcement_states[:plan_owner_id].eq(owners[:id])
-              .and(enforcement_states[:plan_owner_type].eq(name))
+              .and(enforcement_states[:plan_owner_type].eq(PlanOwnerIdentity.type_for(self)))
               .and(enforcement_states[:exceeded_at].not_eq(nil))
             )
             .join_sources
@@ -217,7 +217,7 @@ module PricingPlans
 
     def pricing_plan_overridden?
       return false unless respond_to?(:id) && id.present?
-      Assignment.exists?(plan_owner_type: self.class.name, plan_owner_id: id)
+      Assignment.exists?(PlanOwnerIdentity.conditions_for(self))
     end
 
     def plan_assignment
@@ -226,7 +226,7 @@ module PricingPlans
 
     def pricing_plan_override
       return nil unless respond_to?(:id) && id.present?
-      Assignment.find_by(plan_owner_type: self.class.name, plan_owner_id: id)
+      Assignment.find_by(PlanOwnerIdentity.conditions_for(self))
     end
 
     def pricing_plan_override_source
@@ -257,10 +257,76 @@ module PricingPlans
       )
     end
 
-    # Features
+    # Features. True when the owner is entitled to the feature by ANY source:
+    # the resolved plan carries it, the plan grandfathers it and the owner's
+    # qualifying relationship predates the cutoff, or the owner holds an
+    # active per-owner grant. Every caller of plan_allows? (and the
+    # plan_allows_x? sugar)
+    # honors grandfathering and grants with no app changes.
     def plan_allows?(feature_key)
-      plan = current_pricing_plan
-      plan&.allows_feature?(feature_key) || false
+      feature_entitlement_source(feature_key).present?
+    end
+
+    # Why is (or isn't) this owner entitled to a feature?
+    # => :plan | :grandfather | :grant | nil
+    def feature_entitlement_source(feature_key)
+      resolution = current_pricing_plan_resolution
+      plan = resolution.plan
+
+      return :plan if plan&.allows_feature?(feature_key)
+
+      if plan&.grandfathers_feature?(
+        feature_key,
+        relationship_started_at: pricing_relationship_started_at(resolution)
+      )
+        return :grandfather
+      end
+
+      return :grant if FeatureGrant.active_for?(self, feature_key)
+
+      nil
+    end
+
+    # The earliest qualifying relationship timestamp carried by the current
+    # resolution. An assignment always belongs to its resolved plan. An
+    # underlying subscription only participates when its processor price maps
+    # to that same plan, preventing an old subscription on a different plan
+    # from manufacturing grandfather rights for a new override.
+    def pricing_relationship_started_at(resolution = current_pricing_plan_resolution)
+      timestamps = []
+      timestamps << resolution.assignment.created_at if resolution.assignment?
+
+      subscription = resolution.subscription
+      if subscription.respond_to?(:processor_plan) && subscription.respond_to?(:created_at)
+        subscription_plan = PlanResolver.plan_for_processor_plan(subscription.processor_plan)
+        timestamps << subscription.created_at if subscription_plan&.key == resolution.plan_key
+      end
+
+      timestamps.compact.min
+    end
+
+    # Per-owner feature grants: individual, auditable exceptions on top of
+    # plan resolution (comps, beta access, sales exceptions, promises that
+    # must survive cancellation). See PricingPlans::FeatureGrant.
+    def grant_feature!(feature_key, source: "manual", note: nil, expires_at: nil)
+      FeatureGrant.grant_to!(self, feature_key, source: source, note: note, expires_at: expires_at)
+    end
+
+    # Revokes active grants for the feature (audit rows are kept, stamped
+    # with revoked_at). Plan- and grandfather-sourced entitlements are
+    # config, not grants, and are not affected.
+    def revoke_feature!(feature_key, note: nil)
+      FeatureGrant.revoke_for!(self, feature_key, note: note)
+    end
+
+    def feature_granted?(feature_key)
+      FeatureGrant.active_for?(self, feature_key)
+    end
+
+    def feature_grants
+      return FeatureGrant.none unless FeatureGrant.table_ready?
+
+      FeatureGrant.where(PlanOwnerIdentity.conditions_for(self))
     end
 
     # Syntactic sugar for feature checks: