pricing_plans 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a22c4cf12c06ba9c2e7d649811c286044ae8ff5f9586bea223584fa10b054e4
-  data.tar.gz: 55ee30afed8af0fd32018ca6d706ab0efe4cd745346fc24787d90ddbcf815071
+  metadata.gz: b6b80d22fc74b3afafd8f850f0bbe401c9af56d9dad8102233c48e4e332f1b62
+  data.tar.gz: a03538e62a477cb3ba9f90df6e27de51a48d7b348f2aef96dd7cca0dd997bf88
 SHA512:
-  metadata.gz: bf40f8507ad67ca84c0e46e390db6fdb65e13ea247f5f1a12446c88ec6eaff59d0b519f2951538a59858f2b4222c4257112c5f13d4697a78fc84124e6c713782
-  data.tar.gz: 2a3906414a684300257e1b20b1f4b3cbd278ef7631c7a4f7c675f006483cb107145c323e61072e0fe2fe91976ca140b86dc617d3a14cc1495a010cf8c897c19a
+  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
@@ -134,4 +131,4 @@ Style/GlobalVars:
 
 # Database-related
 Style/NumericLiterals:
-  Enabled: false  # Allow raw numbers in database IDs/amounts
+  Enabled: false  # Allow raw numbers in database IDs/amounts

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,33 @@
+## [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`
+- Require explicit `source:` provenance when creating overrides through the new API
+- Remove the implicit `"manual"` source default from newly generated assignment tables; legacy APIs still supply it explicitly for compatibility
+- Add matching explicit `PlanResolver` and `Assignment` entry points, plus symmetric `override_pricing_plan_for!` and `clear_pricing_plan_override_for!` helpers on `Limitable` models, for lower-level use cases
+- Add override-oriented provenance readers to `PlanResolution` while preserving its assignment-oriented compatibility readers
+- Deprecate the ambiguous `assign_pricing_plan!`, `remove_pricing_plan!`, `assign_plan_manually!`, `remove_manual_assignment!`, `assign_plan_to`, and `remove_assignment_for` APIs through a gem-specific Active Support deprecator
+- Guard legacy assignments of the configured default plan with configurable `:allow`, `:warn`, or `:raise` behavior; upgraded applications default to `:warn`, while newly generated initializers choose the safer `:raise`
+- Clarify that ordinary free/default accounts should remain unassigned and that intentional default-tier pinning remains supported through the explicit override API
+
 ## [0.4.1] - 2026-08-24
 
 - **Never 500 a pricing page when Stripe is unreachable**: `Plan#currency_symbol` was the one Stripe lookup without a rescue — a Stripe outage, rate limit, or missing API key (any test/CI environment) raised straight through the pricing page. It now degrades to `default_currency_symbol` like every other presentation method (#24)

data/README.md

@@ -160,12 +160,25 @@ 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` 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::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.
+  - How it's used: `PlanResolver` checks explicit override → Pay subscription → configured default. Every persisted override takes precedence over subscription-based plans, including an override whose key happens to equal the configured default.
+  - Intention-revealing API: call `plan_owner.override_pricing_plan!(:pro, source: "admin")` to create or update an override, and `plan_owner.clear_pricing_plan_override!` to resume normal subscription/default resolution.
+  - Provenance helpers: `pricing_plan_overridden?`, `pricing_plan_override`, and `pricing_plan_override_source` expose the override directly. `current_pricing_plan_resolution` preserves both entitlement and billing context when an override and a subscription coexist.
+
+An ordinary free/default account needs no assignment row:
+
+```ruby
+# Intentional exception: pin this organization to Pro independently of billing.
+organization.override_pricing_plan!(:pro, source: "customer_success_gift")
+
+# Resume automatic Pay subscription / configured default resolution.
+organization.clear_pricing_plan_override!
+```
+
+The old `assign_pricing_plan!` and `remove_pricing_plan!` names are deprecated because they hide the override semantics. See [Check and explicitly override plans](docs/03-model-helpers.md#check-and-explicitly-override-plans) for migration and strict-mode guidance.
 
 - `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.
@@ -175,6 +188,10 @@ The `pricing_plans` gem needs three new models in the schema in order to work: `
   - 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:
@@ -196,7 +213,7 @@ Enforcing pricing plans is one of those boring plumbing problems that look easy
 
 ## Downgrades and overages
 
-When a customer moves to a lower plan (via Stripe/Pay or manual assignment), the new plan’s limits start applying immediately. Existing resources are never auto‑deleted by the gem; instead:
+When a customer moves to a lower plan (via Stripe/Pay or an explicit override), the new plan’s limits start applying immediately. Existing resources are never auto‑deleted by the gem; instead:
 
 - **Persistent caps** (e.g., `:projects, to: 3`): We count live rows. If the account is now over the new cap, creations will be blocked (or put into grace/warn depending on `after_limit`). Users must remediate by deleting/archiving until under cap.
 - 
@@ -219,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
 
@@ -188,7 +193,7 @@ Callback timing:
 
 ```ruby
 # pro allows 3 custom models per month
-PricingPlans::Assignment.assign_plan_to(org, :pro)
+org.override_pricing_plan!(:pro, source: "test_setup")
 
 travel_to(Time.parse("2025-01-15 12:00:00 UTC")) do
   3.times { org.custom_models.create!(name: "Model") }
@@ -457,7 +462,7 @@ end
 **Important notes:**
 - Hidden plans can be the `default!` plan (common pattern for "unsubscribed" users)
 - Hidden plans **cannot** be the `highlighted!` plan (validation error - highlighted plans must be visible)
-- Users can still be on hidden plans (via Pay subscription, manual assignment, or default)
+- Users can still be on hidden plans (via Pay subscription, an explicit pricing plan override, or the configured default)
 - Internal APIs (`Registry.plans`, `PlanResolver`) can still access hidden plans
 - Pay gem can still resolve subscriptions to hidden plans (useful for grandfathered customers)
 

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.
@@ -290,18 +306,64 @@ You can also use the top-level equivalents if you prefer: `PricingPlans.severity
 
 ## Other helpers and methods
 
-### Check and override plans
+### Check and explicitly override plans
+
+An override is an intentional exception to normal plan resolution. It is useful for gifts, employee accounts, support interventions, demos, and grandfathering. The method names deliberately say **override** because an override always takes precedence over both Pay subscriptions and the configured default:
+
+```ruby
+user.current_pricing_plan                             # => PricingPlans::Plan
+user.current_pricing_plan_source                      # => :assignment, :subscription, :default
+user.current_pricing_plan_resolution                  # => PricingPlans::PlanResolution
+
+user.override_pricing_plan!(:pro, source: "admin")   # create/update an explicit override
+user.pricing_plan_overridden?                         # => true
+user.pricing_plan_override                            # => PricingPlans::Assignment
+user.pricing_plan_override_source                     # => "admin"
+user.clear_pricing_plan_override!                     # resume subscription/default resolution
+```
+
+> [!WARNING]
+> Explicitly overriding to the configured default plan is still an override. For
+> example, `user.override_pricing_plan!(:free, source: "admin_downgrade")`
+> creates an assignment row and continues to take precedence over future Pay
+> subscriptions. That behavior supports intentional default-tier pinning. For an
+> ordinary free/default account, create no assignment. If an override already
+> exists, call `user.clear_pricing_plan_override!` to resume normal resolution.
+
+The `source:` keyword is required by the explicit API. Use a stable, auditable description of why the exception exists—such as `"admin"`, `"customer_success_gift"`, `"employee_access"`, or `"legacy_import"`. The source is provenance; it does not alter precedence. Every override wins regardless of its source label.
+
+Newly generated assignment tables do not have a database default for `source`, so direct model writes must also state their provenance. Applications installed with an older gem version may still have the historical `"manual"` database default; the explicit public API does not rely on it.
+
+#### Migrating from the old assignment API
+
+`assign_pricing_plan!` and `remove_pricing_plan!` are deprecated because their names do not reveal that they create and clear persistent overrides. Replace them directly:
 
-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)
+# Before: ambiguous and source defaulted silently to "manual"
+user.assign_pricing_plan!(:pro)
+user.remove_pricing_plan!
+
+# After: intent and provenance are explicit
+user.override_pricing_plan!(:pro, source: "admin")
+user.clear_pricing_plan_override!
 ```
 
-**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.
+Legacy calls continue to work during the deprecation window and emit a gem-specific Active Support deprecation warning. Assigning the configured default through a legacy API receives an additional guard because it is usually accidental. Its behavior is configurable:
+
+```ruby
+PricingPlans.configure do |config|
+  # :warn  — default for upgraded applications; preserve behavior and warn
+  # :raise — recommended; reject legacy default-plan assignments before writing
+  # :allow — migration escape hatch; emit only the general deprecation warning
+  config.legacy_default_plan_assignment_behavior = :raise
+end
+```
+
+The strict `:raise` behavior raises `PricingPlans::LegacyDefaultPlanAssignmentError` and writes no assignment. It never blocks the explicit `override_pricing_plan!` API, even when the target is the default plan, because that method already states the caller's intent. Newly generated initializers use `:raise`.
+
+The low-level legacy methods—`PricingPlans::PlanResolver.assign_plan_manually!`, `PricingPlans::PlanResolver.remove_manual_assignment!`, `PricingPlans::Assignment.assign_plan_to`, and `PricingPlans::Assignment.remove_assignment_for`—are deprecated under the same policy. Prefer `PlanResolver.override_pricing_plan_for!`, `PlanResolver.clear_pricing_plan_override_for!`, `Assignment.create_or_update_pricing_plan_override_for!`, and `Assignment.clear_pricing_plan_override_for!` when a lower-level API is genuinely necessary. Models that include `PricingPlans::Limitable` also expose the symmetric class-level pair `override_pricing_plan_for!` and `clear_pricing_plan_override_for!` for compatibility with their previous owner-aware assignment helper.
+
+**Performance note:** Each plan/provenance helper performs a fresh database lookup. If you need both the effective plan and its provenance, call `current_pricing_plan_resolution` once and read both from that object.
 
 If you need the full provenance, use the resolution object:
 
@@ -309,13 +371,18 @@ If you need the full provenance, use the resolution object:
 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.source                            # => :assignment (compatibility value)
+resolution.pricing_plan_overridden?           # => true
+resolution.pricing_plan_override              # => PricingPlans::Assignment | nil
+resolution.pricing_plan_override_source       # => "admin" | "legacy_import" | nil
 resolution.subscription                      # => Pay subscription | nil
+
+# Storage-oriented compatibility readers remain available:
+resolution.assignment                        # => same object as pricing_plan_override
+resolution.assignment_source                 # => same value as pricing_plan_override_source
 ```
 
-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.
+This distinction matters: the **effective pricing plan** controls entitlements and limits inside your app, while the **Pay/Stripe subscription state** is billing-facing. An explicit override may intentionally control entitlements while the underlying subscription remains available for billing operations. Clearing the override does not cancel or modify billing; it simply lets subscription/default resolution take control again.
 
 **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.
 

data/docs/06-gem-compatibility.md

@@ -14,10 +14,24 @@ There's nothing to do on your end to make `pricing_plans` work with `pay`!
 
 As long as your `pricing_plans` config (`config/initializers/pricing_plans.rb`) contains a plan with the correct `stripe_price` ID, whenever a subscription to that Stripe price ID is found through the `pay` gem, `pricing_plans` will understand the user is subscribed to that plan automatically, and will start enforcing the corresponding limits.
 
-The way `pricing_plans` works doesn't require any data migration, or callback setup, or any manual action. You don't need to call `assign_pricing_plan!` at all at any point, unless you're trying to something like overriding a plan, gifting users access to plans without any payment, or things like that.
+The way `pricing_plans` works doesn't require any data migration, callback setup, or assignment during signup. Do not call an override API for ordinary plan selection or after a successful Pay checkout: Pay subscriptions are discovered automatically.
+
+Use `plan_owner.override_pricing_plan!(:pro, source: "customer_success_gift")` only when you deliberately want an exception that wins over billing. In particular, do not override to the default/free plan during ordinary signup or free-plan selection. Leave the owner without an override—or call `plan_owner.clear_pricing_plan_override!`—to use Pay/default resolution normally.
+
+The deprecated `assign_pricing_plan!` API now warns, and upgraded applications can turn accidental legacy default-plan assignments into errors:
+
+```ruby
+PricingPlans.configure do |config|
+  config.legacy_default_plan_assignment_behavior = :raise
+end
+```
+
+Newly generated initializers enable this strict behavior. Intentional default-tier pinning remains available through the self-documenting explicit API: `plan_owner.override_pricing_plan!(:free, source: "admin_downgrade")`.
 
 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:
 >
@@ -33,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: "../"