pricing_plans 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8003fe05eaafc824f16d2c6dd72f067c04fd9417f066a1a9e9197f42d30518e0
-  data.tar.gz: 512a6cc888ce5261ecd37fb7b59e9bd5c16c3571d754154b0ee0e30c385e9c36
+  metadata.gz: b6b80d22fc74b3afafd8f850f0bbe401c9af56d9dad8102233c48e4e332f1b62
+  data.tar.gz: a03538e62a477cb3ba9f90df6e27de51a48d7b348f2aef96dd7cca0dd997bf88
 SHA512:
-  metadata.gz: 617a80ea706ea417eb1f8ad8a8676c9690d852a66b454793ba47efe2bb4d112873b13f8a7e7fec7e6e9c9ed7833ae3d36f834be519f9b90bbc4ef18cac6de6d9
-  data.tar.gz: 6e86e014b7a3652a48725677819c324fedf23f924db740f30a2f2cf05a3f138673edf8b9d2d95a8c9fcd915e75438613b335fefad3867c1be0fb10389df71353
+  metadata.gz: 605f1beb4fdc85b9b8b26b2e8da96fb620f9b8bd28ecadf4688d5b00cf002aaa979155abeccef100f50e3a9b9932095506b691e0bbd84f4727f0cebdaaba40bd
+  data.tar.gz: 3b8ecc71305850c3760d3a96ee530c2069a099806733223280b834cd368fbe9773d8483f5a7fa02744fd0704206d6a142a0933d8837133c28ca85a93fc0d1860

data/.rubocop.yml

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require:
+plugins:
   - rubocop-minitest
   - rubocop-performance
 
@@ -11,6 +11,7 @@ AllCops:
     - 'bin/**/*'
     - 'vendor/**/*'
     - 'test/dummy/**/*'
+    - 'tmp/**/*'
     - 'db/migrate/**/*'  # Generated migrations
     - 'lib/generators/**/templates/**/*'  # Generator templates
 
@@ -42,7 +43,7 @@ Style/FrozenStringLiteralComment:
   EnforcedStyle: always
 
 Style/ClassAndModuleChildren:
-  EnforcedStyle: compact
+  EnforcedStyle: nested
 
 Style/GuardClause:
   MinBodyLength: 3
@@ -82,7 +83,7 @@ Metrics/PerceivedComplexity:
   Max: 10
 
 # Naming
-Naming/PredicateName:
+Naming/PredicatePrefix:
   ForbiddenPrefixes:
     - 'is_'
   AllowedMethods:
@@ -102,10 +103,6 @@ Minitest/MultipleAssertions:
 Minitest/AssertTruthy:
   Enabled: false  # Allow assert instead of assert_equal true
 
-# Rails-specific (even though we don't have full Rails)
-Style/Rails/HttpStatus:
-  Enabled: false
-
 # Custom overrides for this gem
 Style/AccessorGrouping:
   Enabled: false  # Allow separate attr_reader/attr_writer

data/.simplecov

@@ -3,15 +3,15 @@
 # SimpleCov configuration file (auto-loaded before test suite)
 # This keeps test_helper.rb clean and follows best practices
 
-SimpleCov.start do
+SimpleCov.configure do
   # Use SimpleFormatter for terminal-only output (no HTML generation)
   formatter SimpleCov::Formatter::SimpleFormatter
 
   # Track coverage for the lib directory (gem source code)
-  add_filter "/test/"
+  skip "/test/"
 
   # Track the lib and app directories
-  track_files "{lib,app}/**/*.rb"
+  cover "{lib,app}/**/*.rb"
 
   # Enable branch coverage for more detailed metrics
   enable_coverage :branch
@@ -20,13 +20,14 @@ SimpleCov.start do
   minimum_coverage line: 80, branch: 65
 
   # Disambiguate parallel test runs
-  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV['TEST_ENV_NUMBER']
+  test_env_number = ENV.fetch("TEST_ENV_NUMBER", nil)
+  command_name "Job #{test_env_number}" if test_env_number
 end
 
 # Print coverage summary to terminal after tests complete
 SimpleCov.at_exit do
   SimpleCov.result.format!
-  puts "\n" + "=" * 60
+  puts "\n#{'=' * 60}"
   puts "COVERAGE SUMMARY"
   puts "=" * 60
   puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"

data/Appraisals

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1.0"
+end
+
 appraise "rails-7.2" do
-  gem "rails", "~> 7.2.3"
+  gem "rails", "~> 7.2.3", ">= 7.2.3.2"
 end
 
 appraise "rails-8.1" do

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [0.6.0] - 2026-08-31
+
+**Repricing without app migrations: grandfathering and per-owner feature grants.**
+
+- Add the `grandfather` plan DSL: `grandfather :feature, subscribed_before: <time>` declares that owners whose qualifying pricing relationship predates the cutoff keep a feature the plan no longer `allows`. Pure configuration — no columns, no backfills, no rake tasks; the initializer stays the git-versioned record of every pricing change
+- Grandfather eligibility uses the older of the current assignment and same-plan subscription `created_at`. It models a continuous pricing relationship (Pay keeps the same subscription row across price swaps, and updating an assignment keeps that row's age), not unavailable plan-change history; lapse/re-subscribe or clear/reassign resets the corresponding timestamp, while exact materialized cohorts belong in feature grants
+- Add `PricingPlans::FeatureGrant` and the per-owner grants API: `grant_feature!`, `revoke_feature!`, `feature_granted?`, `feature_grants` — individual, auditable exceptions (comps, beta access, sales promises, remediation) that attach to the owner and survive plan changes and cancellation until expiry or revocation; revocation stamps `revoked_at` and keeps the row as history
+- `plan_allows?` (and the `plan_allows_x?` sugar) now honors all three entitlement sources — plan, grandfather, grant — so existing app gates pick everything up with zero changes; `feature_entitlement_source` answers which one applied (`:plan | :grandfather | :grant | nil`)
+- Keep `past_due` Pay subscriptions entitled while the processor retries payment, and prefer a current subscription whose processor price exists in the plan registry when an owner has several
+- Do not let a stale `past_due` status re-entitle a Stripe subscription after an already-scheduled `void` pause becomes effective; future pauses remain entitled through their scheduled date
+- Use Rails' canonical polymorphic owner identity throughout assignments, grants, and admin scopes (including STI), and serialize grant mutations on the owner row so idempotent writes remain race-safe
+- Declaring `grandfather` for a feature the plan still `allows` raises a `ConfigurationError` (one of the two lines is a mistake); unparseable cutoffs raise too, Rails `TimeWithZone` values are accepted, and date-only cutoffs are read as midnight UTC
+- The install generator now creates `pricing_plans_feature_grants`; existing apps add it with the new `rails generate pricing_plans:grants` (plan-level grandfathering needs no table at all — reads degrade silently without it, grant writes raise with instructions)
+- Advance the deprecation horizon to 0.7.0 (the APIs deprecated in 0.5.0 live one more minor)
+- Make grace windows a validated invariant: `grace` defaults only for `:grace_then_block`, must be a positive finite numeric duration of at least one second, and cannot be declared at all (including `nil`/`false`) with `:block_usage`/`:just_warn`. Previously every limit silently carried `grace: 7.days`, and malformed values could make reporting disagree with enforcement
+- `OverageReporter` items now carry `grace_window` (the configured window on the target plan, enforced-only by construction) alongside the runtime `grace_active`/`grace_ends_at`, so downgrade and dunning copy can say "after a N-day grace window" without re-deriving enforcement rules
+- Plan resolution now reads Pay's underlying `payment_processor` association without invoking Pay's auto-provisioning reader, so asking for the current plan can never create a `pay_customers` row; PORO/legacy adapters still use their public reader
+- Add docs/07-repricing.md (the full grandfathering + grants guide), make plan_allows? entitlement-awareness explicit in the model-helpers doc, and bless two long-requested recipes in the docs: reacting to plan changes via Pay lifecycle hooks (#13) and running multiple plan-owner models side by side (#22)
+
 ## [0.5.0] - 2026-08-31
 
 - Add intention-revealing pricing plan override APIs: `override_pricing_plan!`, `clear_pricing_plan_override!`, `pricing_plan_overridden?`, `pricing_plan_override`, and `pricing_plan_override_source`

data/README.md

@@ -160,7 +160,7 @@ Integrating payment processing (Stripe, `pay`, etc.) is relatively straightforwa
 
 ## Why the models?
 
-The `pricing_plans` gem needs three new models in the schema in order to work: `Assignment`, `EnforcementState`, and `Usage`. Why are they needed?
+The `pricing_plans` gem uses four models: `Assignment`, `EnforcementState`, `Usage`, and `FeatureGrant`. Why are they needed?
 
 - `PricingPlans::Assignment` stores explicit pricing plan overrides independently of the billing system. This is useful for gifts, employee access, demos, support interventions, and grandfathered customers.
   - What: A `plan_key` and a required provenance label such as `"admin"`, `"customer_success_gift"`, or `"legacy_import"`. There can be only one override per plan owner.
@@ -188,6 +188,10 @@ The old `assign_pricing_plan!` and `remove_pricing_plan!` names are deprecated b
   - What: `period_start`, `period_end`, and a monotonic `used` counter with a last-used timestamp.
   - How it’s used: On create of the metered model, we increment or upsert the usage for the current window (based on `PeriodCalculator`). Reads power `remaining`, `percent_used`, and warning thresholds.
 
+- `PricingPlans::FeatureGrant` stores optional per-owner feature exceptions independently of the current plan.
+  - What: A feature key, provenance source, optional note/expiry, and revocation timestamp.
+  - How it’s used: Active grants participate in `plan_allows?`; revocation retains the row so the grant/revocation lifecycle remains inspectable. Apps upgrading from before 0.6.0 add this table with `rails generate pricing_plans:grants && rails db:migrate`.
+
 ## Gem features
 
 Enforcing pricing plans is one of those boring plumbing problems that look easy from a distance but get complex when you try to engineer them for production usage. The poor man's implementation of nested ifs shown in the example above only get you so far, you soon start finding edge cases to consider. Here's some of what we've covered in this gem:
@@ -232,6 +236,49 @@ Notes:
 - If you provide a `config.message_builder`, it’s used to customize copy for the `:overage_report` context.
 - This reporter works regardless of whether any controller/model action has been hit; it reads live counts and current period usage.
 
+## Changing your pricing: grandfathering and feature grants
+
+Sooner or later you'll reprice: a feature that used to be on a cheap plan moves to a higher one. The customers who already pay you should keep what they signed up for — and that should not require new columns, backfills, or rake tasks in your app. (Full guide: [docs/07-repricing.md](/docs/07-repricing.md).)
+
+### Grandfathering (declarative, zero state)
+
+Remove the feature from the plan's `allows`, and declare the grandfather right next to it:
+
+```ruby
+plan :indie do
+  allows :api_access                 # :distribution moved to :starter on 2026-08-31
+  grandfather :distribution, subscribed_before: "2026-09-01"
+end
+```
+
+That's the whole migration. Owners whose qualifying pricing relationship predates the cutoff keep the feature; everyone who arrives later doesn't. `plan_allows?(:distribution)` (and the `plan_allows_distribution?` sugar) just keep working everywhere — the gate code in your app doesn't change at all. Your initializer stays the single, git-versioned record of what changed and when.
+
+Semantics, precisely:
+
+- **Eligibility time** is the older of the current manual assignment and a current subscription whose processor price maps to the same resolved plan. An old subscription on another plan cannot make a new override eligible.
+- Pay keeps a subscription's original `created_at` when its price is swapped; changing the plan key on an existing manual assignment likewise keeps that assignment row's age. This measures a **continuous pricing relationship**, not the exact date the current plan or price was selected. That is usually the desired grandfathering policy; use grants if you need a frozen, exact historical cohort.
+- Grandfathering rides that continuous relationship: cancel and re-subscribe, or clear and later recreate an assignment, and you re-enter at current pricing. For a promise that must survive anything, use a grant (below).
+- Cutoffs accept a `Time`, `ActiveSupport::TimeWithZone`, `Date`, or `String`; date-only values are read as **midnight UTC**.
+- Declaring `grandfather` for a feature the plan still `allows` raises a configuration error — one of the two lines is a mistake.
+
+### Feature grants (per-owner exceptions)
+
+For individual exceptions — comps, beta access, sales promises, support remediation, or a grandfather that must survive cancellation — grant the feature to the owner directly:
+
+```ruby
+org.grant_feature!(:distribution, source: "founder_comp", note: "conference friend")
+org.grant_feature!(:sso, source: "sales", expires_at: 30.days.from_now)
+
+org.plan_allows?(:sso)                      # => true (source-aware predicate below)
+org.feature_entitlement_source(:sso)        # => :plan | :grandfather | :grant | nil
+org.feature_granted?(:sso)                  # => true (active grant row exists)
+
+org.revoke_feature!(:sso, note: "eval over") # keeps the row, stamps revoked_at
+org.feature_grants                           # retained grant/revocation history
+```
+
+Grants live in the `pricing_plans_feature_grants` table (created by the install generator; apps upgrading from < 0.6.0 add it with `rails generate pricing_plans:grants && rails db:migrate`). They attach to the owner, not the plan, so they survive plan changes and cancellations until expiry or revocation. Rows are never deleted by the API: revoking stamps `revoked_at`, preserving each grant/revocation lifecycle. Re-granting while a grant is active updates that row; it is not an event-by-event audit log of field edits.
+
 ### Override checks
 
 Some times you'll want to override plan limits / feature gating checks. A common use case is if you're responding to a webhook (like Stripe), you'll want to process the webhook correctly (bypassing the check) and maybe later handle the limit manually.

data/docs/01-define-pricing-plans.md

@@ -129,12 +129,17 @@ PricingPlans.configure do |config|
 end
 ```
 
+`grace` must be a positive numeric duration of at least one second. Omitting it
+for `:grace_then_block` defaults to `7.days`. Do not pass `grace` (even as
+`nil` or `false`) to `:block_usage` or `:just_warn`; those modes never honor a
+grace window and configuration fails fast instead of storing misleading data.
+
 In summary: persistent caps count live rows (per plan owner model). When over the cap:
   - `:just_warn` → validation passes; use controller guard to warn.
   - `:block_usage` → validation fails immediately (uses `error_after_limit` if set).
   - `:grace_then_block` → validation fails once grace is considered “blocked” (we track and switch from grace to blocked).
 
-Note: `grace` is only valid with blocking behaviors. We’ll raise at boot if you set `grace` with `:just_warn`.
+Note: `grace` is only valid with `:grace_then_block`. We’ll raise at boot if you declare it with `:block_usage` or `:just_warn`.
 
 ### Per‑period allowances
 

data/docs/03-model-helpers.md

@@ -16,6 +16,16 @@ end
 
 By adding the `PricingPlans::PlanOwner` mixin to a model, you automatically get all the features described below.
 
+### Multiple plan-owner models (two-sided marketplaces)
+
+You can include `PricingPlans::PlanOwner` in more than one model (say, `User` on the consumer side and `Organization` on the company side, each with their own `pay_customer`). Plan resolution is per-owner, so this mostly just works ([#22](https://github.com/rameerez/pricing_plans/issues/22)):
+
+- Give each side its own paid plans; a subscription resolves whichever plan matches its Stripe price, regardless of which model holds it.
+- In controllers, point the gem at the right owner per side with a custom plan-owner method (see the [controller helpers](02-controller-helpers.md)) returning `Current.user` or `Current.organization` as appropriate.
+- For pricing pages, tag plans with `meta`data (e.g. `meta audience: "users"` vs `"organizations"`) and filter [`PricingPlans.plans`](01-define-pricing-plans.md#plan-metadata-for-ui-and-presentation) by it, so each side sees only its own ladder.
+
+The one real constraint today: there is a single global `default!` plan (and a single `highlighted!`), shared by every owner model — so keep the default plan generic enough for both sides. First-class plan groups (per-owner-type defaults and highlights) are a candidate for a future release.
+
 ## Link plan limits to your `PlanOwner` model
 
 Now you can link any `has_many` relationships in this model to `limits` defined in your `pricing_plans.rb`
@@ -132,6 +142,12 @@ Of course, there's also dynamic syntactic sugar of the form `plan_allows_<featur
 user.plan_allows_api_access?
 ```
 
+`plan_allows?` is entitlement-aware, not just plan-aware: it also honors [grandfathered features and per-owner grants](07-repricing.md) (since 0.6.0), so it stays the one predicate to gate on even after you reprice. To see *why* an owner is entitled:
+
+```ruby
+user.feature_entitlement_source(:api_access)  # => :plan | :grandfather | :grant | nil
+```
+
 ## Usage and limits status
 
 Checking the current usage with respect to plan limits comes in handy, especially when [building views](/docs/04-views.md). The following methods are useful to build warning / alert snippets, upgrade prompts, usage trackers, etc.

data/docs/06-gem-compatibility.md

@@ -30,6 +30,8 @@ Newly generated initializers enable this strict behavior. Intentional default-ti
 
 As long as a matching `stripe_price` is found in the `pricing_plans.rb` initializer, the gem will know a user subscribed to that Stripe price ID is under the corresponding plan. Essentially, the gem just looks at the current `pay` subscriptions of your user. If a matching price ID is found in the `pricing_plans` configuration file, it enforces the corresponding limits.
 
+Plan resolution treats Pay subscriptions as entitlement-bearing while they are active, trialing, in a cancellation grace period, or `past_due`. A failed renewal therefore does not abruptly downgrade a customer while the processor is still retrying payment; canceled and unpaid subscriptions no longer qualify. If an owner has multiple current subscriptions, the gem prefers one whose `processor_plan` matches the configured registry instead of blindly taking the first row.
+
 > [!TIP]
 > To make your `pricing_plans` gem config work across environments (production, development, etc.) instead of defining price IDs statically like this in the config:
 >
@@ -45,6 +47,39 @@ As long as a matching `stripe_price` is found in the `pricing_plans.rb` initiali
 >
 > You can come up with similar solutions, like adding that config to a plaintext `.yml` file if you don't want to store this info in the credentials file, but this is the overall idea.
 
+### Reacting to plan changes ("repackaging")
+
+`pricing_plans` resolves plans lazily — it reads the current Pay subscription when you ask, and never writes anything on plan changes. That's a feature (no sync bugs, no migrations), but it means the gem has no built-in "plan changed" callback to run side effects like disabling excess resources on downgrade or re-enabling them on upgrade.
+
+The blessed recipe (worked out in [#13](https://github.com/rameerez/pricing_plans/issues/13)) is to hook Pay's own subscription lifecycle, which is exactly where plan changes become visible:
+
+```ruby
+# app/models/concerns/pay_extension.rb
+module PayExtension
+  extend ActiveSupport::Concern
+
+  included do
+    after_commit :repackage_for_subscription, on: [ :create, :update, :destroy ]
+  end
+
+  def repackage_for_subscription
+    owner = customer&.owner
+    return unless owner.is_a?(Organization)
+
+    RepackageService.new(owner).call   # your idempotent per-plan side effects
+  end
+end
+
+# config/initializers/pay.rb
+ActiveSupport.on_load(:pay_subscription) do
+  include PayExtension
+end
+```
+
+Keep the service **idempotent** (safe to run twice) and derive everything from `owner.current_pricing_plan` — that way it also doubles as a backfill job you can run over all owners after changing the rules. Note that if you also use [manual plan overrides](03-model-helpers.md#check-and-explicitly-override-plans), those change plans without touching Pay, so run the same service after calling `override_pricing_plan!` too.
+
+Also consider whether you need repackaging at all: for limits, the gem's own [downgrade semantics](../README.md#downgrades-and-overages) (block writes while over-quota, never delete data) often cover it with no code.
+
 ## `usage_credits` gem
 
 In the SaaS world, pricing plans and usage credits are related in so far credits are usually a part of a pricing plan. A plan would give you, say, 100 credits a month along other features, and users would find that information usually documented in the pricing table itself.

data/docs/07-repricing.md

@@ -0,0 +1,98 @@
+# Repricing: grandfathering and feature grants
+
+Sooner or later you'll change your pricing: a feature that used to live on a cheap plan moves to a higher one. The customers who already pay you should keep what they signed up for — and that should not cost you new columns, backfill migrations, or bypass code in your gates.
+
+`pricing_plans` handles both halves of this natively (since 0.6.0):
+
+- **Grandfathering** — cohort-level policy, declared in your initializer. Zero database state.
+- **Feature grants** — per-owner exceptions (comps, beta access, sales promises), stored and auditable.
+
+Both flow through `plan_allows?` and the `plan_allows_<feature>?` sugar, so every gate you've already written picks them up with no changes.
+
+## Grandfathering (one line, zero state)
+
+Say `:distribution` used to be on your `:indie` plan and now starts at `:starter`. Remove it from `allows`, and declare the grandfather right next to it:
+
+```ruby
+plan :indie do
+  allows      :api_access
+  grandfather :distribution, subscribed_before: "2026-09-01"
+end
+
+plan :starter do
+  allows :api_access, :distribution
+end
+```
+
+That's the entire repricing migration. Owners whose qualifying pricing relationship predates the cutoff keep `:distribution`; everyone who arrives later sees your upgrade gate. Your initializer stays the single, git-versioned record of what changed and when — future-you can read the whole pricing policy in one file.
+
+### The semantics, precisely
+
+- **Eligibility time** is the older of the current manual assignment and a current subscription whose processor price maps to the same resolved plan. A subscription on another plan is ignored, so it cannot manufacture grandfather rights for a new override.
+- Pay updates the same subscription row during an in-place price swap, preserving its original `created_at`; changing the plan key on an existing assignment also keeps that row's age. Grandfathering therefore measures a **continuous pricing relationship**, not the exact date that the current plan or price was selected. If your policy needs an exact historical plan-enrollment cohort, materialize that cohort with grants instead.
+- Grandfathering rides that continuous relationship. Cancel and re-subscribe, or clear and later recreate an assignment, and the customer re-enters at current pricing. If you promised someone the feature *forever*, that's a grant (below).
+- `active`, trialing, grace-period, and `past_due` subscriptions remain entitlement-bearing; canceled and unpaid subscriptions do not. This keeps access stable while a processor retries a failed payment.
+- Cutoffs accept a `Time`, `ActiveSupport::TimeWithZone`, `Date`, or `String`. Date-only values are read as **midnight UTC**.
+- Owners on the default (free) plan have no qualifying relationship timestamp and are never grandfathered.
+- Declaring `grandfather` for a feature the plan still `allows` raises a `ConfigurationError` at boot — one of those two lines is a mistake.
+
+> [!TIP]
+> Pick a cutoff just **after** your deploy moment (e.g. tomorrow's date), so anyone who signs up while you're shipping the change lands on the generous side of the line.
+
+## Feature grants (per-owner exceptions)
+
+For individual exceptions, grant the feature to the owner directly:
+
+```ruby
+org.grant_feature!(:distribution, source: "founder_comp", note: "conference friend")
+org.grant_feature!(:sso, source: "sales", expires_at: 30.days.from_now)
+
+org.plan_allows?(:sso)          # => true
+org.feature_granted?(:sso)      # => true (an active grant row exists)
+
+org.revoke_feature!(:sso, note: "eval over")
+org.feature_grants              # retained grant/revocation history
+```
+
+Use grants for:
+
+- **Comps** — a friend, a case study, an influencer.
+- **Beta access** — grant a feature to a handful of owners before it's on any plan.
+- **Sales promises** — "you'll get X while you evaluate", with `expires_at`.
+- **Support remediation** — "we broke your week, here's X until renewal".
+- **A grandfather that must survive cancellation** — grants attach to the owner, not the plan, so they persist through plan changes and cancellation until expiry or revocation.
+
+Grants are **never deleted** by the API: revoking stamps `revoked_at` and keeps the row, preserving each grant/revocation lifecycle. Updating an active grant changes that row; this is not an event-by-event audit log of every field edit.
+
+Granting the same feature twice updates the active grant instead of stacking; revoking and granting again creates a fresh row (history preserved).
+
+### The table
+
+Fresh installs get the `pricing_plans_feature_grants` table from the install generator. If you installed pricing_plans before 0.6.0, add it with:
+
+```bash
+rails generate pricing_plans:grants && rails db:migrate
+```
+
+Declarative grandfathering needs **no table at all**. Without the table, grant *reads* silently report no grants, and grant *writes* raise with the command above.
+
+## Which one applied?
+
+When you're debugging or answering a support ticket, ask the owner directly:
+
+```ruby
+org.feature_entitlement_source(:distribution)
+# => :plan         (the resolved plan allows it)
+# => :grandfather  (qualifying pricing relationship predates the cutoff)
+# => :grant        (an active per-owner grant)
+# => nil           (not entitled)
+
+org.pricing_relationship_started_at
+# => qualifying same-plan subscription / assignment timestamp (or nil)
+```
+
+## A real-world example
+
+[LicenseSeat](https://licenseseat.com) moved its software-distribution feature from its $9 plan to its $29 plan. Its feature gates (plain `plan_allows?(:distribution)` calls) didn't change at all — the whole repricing lived in configuration and one data migration.
+
+It's also a worked example of choosing between the two tools. LicenseSeat's promise was to *the exact set of customers subscribed on launch day*, frozen, surviving anything — so it ran a small one-time migration that wrote a durable grant per qualifying subscriber (`grant_feature!` with a dated `source`), rather than declaring the date rule. If your promise is the more common "anyone with us from before the change keeps it while they stay subscribed", the one-line `grandfather` declaration is the whole migration.

data/gemfiles/rails_7.1.gemfile

@@ -0,0 +1,26 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 7.1.0"
+
+group :development do
+  gem "irb"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :development, :test do
+  gem "appraisal"
+  gem "minitest", ">= 5.16", "< 7"
+  gem "minitest-mock"
+  gem "rack-test"
+  gem "railties", ">= 7.1", "< 9"
+  gem "sqlite3", ">= 2.1"
+  gem "ostruct"
+  gem "simplecov", require: false
+end
+
+gemspec path: "../"

data/gemfiles/rails_7.2.gemfile

@@ -3,7 +3,7 @@
 source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
-gem "rails", "~> 7.2.3"
+gem "rails", "~> 7.2.3", ">= 7.2.3.2"
 
 group :development do
   gem "irb"
@@ -14,9 +14,10 @@ end
 
 group :development, :test do
   gem "appraisal"
-  gem "minitest", "~> 6.0"
+  gem "minitest", ">= 5.16", "< 7"
   gem "minitest-mock"
   gem "rack-test"
+  gem "railties", ">= 7.1", "< 9"
   gem "sqlite3", ">= 2.1"
   gem "ostruct"
   gem "simplecov", require: false

data/gemfiles/rails_8.1.gemfile

@@ -14,9 +14,10 @@ end
 
 group :development, :test do
   gem "appraisal"
-  gem "minitest", "~> 6.0"
+  gem "minitest", ">= 5.16", "< 7"
   gem "minitest-mock"
   gem "rack-test"
+  gem "railties", ">= 7.1", "< 9"
   gem "sqlite3", ">= 2.1"
   gem "ostruct"
   gem "simplecov", require: false

data/lib/generators/pricing_plans/grants/grants_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module PricingPlans
+  module Generators
+    # Adds the pricing_plans_feature_grants table to apps that installed
+    # pricing_plans before per-owner feature grants existed (< 0.6.0).
+    # Fresh installs get the table from the install generator and never
+    # need this one.
+    class GrantsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Add the pricing_plans_feature_grants table (upgrade from pricing_plans < 0.6.0)"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "create_pricing_plans_feature_grants.rb.erb",
+                           File.join(db_migrate_path, "create_pricing_plans_feature_grants.rb"),
+                           migration_version: migration_version
+      end
+
+      def display_post_install_message
+        say "\n✅ Feature grants migration created.", :green
+        say "Run 'rails db:migrate', then grant per-owner features with e.g. " \
+            "`owner.grant_feature!(:some_feature, note: \"comp\")`."
+        say "Note: declarative grandfathering " \
+            "(`grandfather :feature, subscribed_before: ...` in a plan) needs no table at all."
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/pricing_plans/grants/templates/create_pricing_plans_feature_grants.rb.erb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class CreatePricingPlansFeatureGrants < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :pricing_plans_feature_grants, id: primary_key_type do |t|
+      t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :feature_key, null: false
+      t.string :source, null: false
+      t.text :note
+      t.datetime :expires_at
+      t.datetime :revoked_at
+
+      t.timestamps
+    end
+
+    add_index :pricing_plans_feature_grants,
+              [ :plan_owner_type, :plan_owner_id, :feature_key ],
+              name: "idx_pricing_plans_feature_grants_lookup"
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [ primary_key_type, foreign_key_type ]
+  end
+end

data/lib/generators/pricing_plans/install/templates/create_pricing_plans_tables.rb.erb

@@ -17,12 +17,12 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     add_index :pricing_plans_enforcement_states,
-              [:plan_owner_type, :plan_owner_id, :limit_key],
+              [ :plan_owner_type, :plan_owner_id, :limit_key ],
               unique: true,
               name: "idx_pricing_plans_enforcement_unique"
 
     add_index :pricing_plans_enforcement_states,
-              [:plan_owner_type, :plan_owner_id],
+              [ :plan_owner_type, :plan_owner_id ],
               name: "idx_pricing_plans_enforcement_plan_owner"
 
     add_index :pricing_plans_enforcement_states,
@@ -42,16 +42,16 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     add_index :pricing_plans_usages,
-              [:plan_owner_type, :plan_owner_id, :limit_key, :period_start],
+              [ :plan_owner_type, :plan_owner_id, :limit_key, :period_start ],
               unique: true,
               name: "idx_pricing_plans_usages_unique"
 
     add_index :pricing_plans_usages,
-              [:plan_owner_type, :plan_owner_id],
+              [ :plan_owner_type, :plan_owner_id ],
               name: "idx_pricing_plans_usages_plan_owner"
 
     add_index :pricing_plans_usages,
-              [:period_start, :period_end],
+              [ :period_start, :period_end ],
               name: "idx_pricing_plans_usages_period"
 
     create_table :pricing_plans_assignments, id: primary_key_type do |t|
@@ -63,13 +63,28 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     end
 
     add_index :pricing_plans_assignments,
-              [:plan_owner_type, :plan_owner_id],
+              [ :plan_owner_type, :plan_owner_id ],
               unique: true,
               name: "idx_pricing_plans_assignments_unique"
 
     add_index :pricing_plans_assignments,
               :plan_key,
               name: "idx_pricing_plans_assignments_plan"
+
+    create_table :pricing_plans_feature_grants, id: primary_key_type do |t|
+      t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :feature_key, null: false
+      t.string :source, null: false
+      t.text :note
+      t.datetime :expires_at
+      t.datetime :revoked_at
+
+      t.timestamps
+    end
+
+    add_index :pricing_plans_feature_grants,
+              [ :plan_owner_type, :plan_owner_id, :feature_key ],
+              name: "idx_pricing_plans_feature_grants_lookup"
   end
 
   private
@@ -79,7 +94,7 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     setting = config.options[config.orm][:primary_key_type]
     primary_key_type = setting || :primary_key
     foreign_key_type = setting || :bigint
-    [primary_key_type, foreign_key_type]
+    [ primary_key_type, foreign_key_type ]
   end
 
   def json_column_type
@@ -87,4 +102,3 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     :json
   end
 end
-

data/lib/generators/pricing_plans/install/templates/initializer.rb

@@ -21,6 +21,12 @@ PricingPlans.configure do |config|
     allows :api_access, :premium_features
     limits :projects, to: 25, after_limit: :grace_then_block, grace: 7.days
 
+    # Repricing later? When you move a feature to a higher plan, existing
+    # subscribers keep it with one declarative line (no columns, no backfill):
+    #   grandfather :premium_features, subscribed_before: "2027-01-01"
+    # One-off exceptions (comps, betas) are per-owner grants instead:
+    #   owner.grant_feature!(:premium_features, note: "comp")
+
     highlighted!
   end
 

data/lib/pricing_plans/engine.rb

@@ -14,6 +14,7 @@ module PricingPlans
         require "pricing_plans/models/enforcement_state"
         require "pricing_plans/models/usage"
         require "pricing_plans/models/assignment"
+        require "pricing_plans/models/feature_grant"
       end
     end