pricing_plans 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8003fe05eaafc824f16d2c6dd72f067c04fd9417f066a1a9e9197f42d30518e0
-  data.tar.gz: 512a6cc888ce5261ecd37fb7b59e9bd5c16c3571d754154b0ee0e30c385e9c36
+  metadata.gz: 69a00b6a4bbe7bc513e707744b890a0fbcea4161f322f5a5d3384ae1775be130
+  data.tar.gz: 6647732b7368f398bb62eaa1968af7b0132ef68f2ad89f858aa507922c794e4d
 SHA512:
-  metadata.gz: 617a80ea706ea417eb1f8ad8a8676c9690d852a66b454793ba47efe2bb4d112873b13f8a7e7fec7e6e9c9ed7833ae3d36f834be519f9b90bbc4ef18cac6de6d9
-  data.tar.gz: 6e86e014b7a3652a48725677819c324fedf23f924db740f30a2f2cf05a3f138673edf8b9d2d95a8c9fcd915e75438613b335fefad3867c1be0fb10389df71353
+  metadata.gz: f77dce78f0d0fa86cd195f6b7fab99992634cb17ed5543973fbb3afa0774da80ed1236ea5cb712df1e2b9e58bb2925c7a476942f8aab0720926332c3cbc89a35
+  data.tar.gz: 42add5c893313c1dddbbe7af5c54882872e6d75b6551d70c074e5e44ed96e54be72e778b40e7aacbb5daf222499b0ff7d208f165d42c766b9fb62217b79e5a0a

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,37 @@
+## [0.7.0] - 2026-09-05
+
+**Feature passes: bounded, create-only samples on top of feature grants.**
+
+Expiring per-owner grants have existed since 0.6.0 (`grant_feature!` with `expires_at:`). 0.7.0 adds what a sales or support offer needs on top of them:
+
+- `issue_feature_pass!` is create-only: it raises `FeatureGrantConflict` instead of overwriting an existing active grant, so an operator's "issue" button can never shorten a permanent promise. `grant_feature!` keeps its upsert semantics and now preserves a pass's limits and consumption when they are omitted
+- A pass can carry named capacity `limits:` (a hash the app measures against at its write boundary) and a cumulative `usage_limit:` whose `usage_count` the gem reserves atomically. Both are properties of the pass alone: plan and grandfather access carry no named limits, and the app keeps owning its plan quotas exactly as before
+- `feature_access(:feature)` returns a read-only `FeatureAccess` snapshot for UI and preflight: `source`, `grant`, `expires_at`, `limit(:key)`, `usage_limit`, `usage_count`, `remaining_allowance`, `available?`, `check!`
+- `with_feature_access!(:feature, amount:, usage:)` locks a fresh copy of the owner row, resolves access again, checks the pass limits and cumulative allowance, reserves `amount`, and yields inside a savepoint; an exception escaping the block rolls back the reservation together with the business write. `FeatureLimitExceeded < FeatureDenied` carries `limit_key`, `allowed`, and `requested`
+- `FeatureGrant#revise!` changes `expires_at`, `limits`, `usage_limit`, or `note` on an active row while preserving consumption, and refuses expired or revoked rows; `revoke!` is serialized with consumption
+- Three additive columns on `pricing_plans_feature_grants` (`limits`, `usage_limit`, `usage_count`) plus a nonnegative check constraint. Fresh installs and `pricing_plans:grants` include them; apps already on the 0.6.x table run `rails generate pricing_plans:passes && rails db:migrate`. Old-schema boolean grants keep working, and bounded writes raise a `ConfigurationError` naming the generator when the columns are missing
+- Full guide: `docs/08-feature-passes.md`
+- The plan-assignment APIs deprecated in 0.5.0 (`assign_pricing_plan!`, `remove_pricing_plan!`, `Assignment.assign_plan_to`, `Assignment.remove_assignment_for`) stay for one more minor: the deprecation horizon moves to 0.8.0 so this feature release carries no removals. They go in 0.8.0 together with the first-class plan-change hook (#13) and plan groups (#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,65 @@ 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.
+
+### Feature passes: time and usage bounded evaluations
+
+Offer a customer a sample without changing billing or replacing an existing promise:
+
+```ruby
+org.issue_feature_pass!(:distribution, source: "sales_evaluation",
+  expires_at: 3.months.from_now,
+  limits: { storage_bytes: 1.gigabyte }, usage_limit: 2.gigabytes)
+```
+
+The [complete feature pass guide](docs/08-feature-passes.md) covers capacity versus
+cumulative consumption, atomic write enforcement, operator controls, upgrade
+precedence, expiry, revocation, and the additive migration for existing apps.
+**Named limits require live measurements at the write boundary**; see
+`with_feature_access!` in the guide before enabling a bounded offer.
+
 ### 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,103 @@
+# 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.
+
+## Bounded feature passes
+
+For create-only sales offers, capacity limits, and cumulative allowances, see the
+[feature passes guide](08-feature-passes.md). Existing grant semantics above remain unchanged.

data/docs/08-feature-passes.md

@@ -0,0 +1,192 @@
+# Feature passes: samples, evaluations, and customer promises
+
+A feature pass grants one plan owner access to a feature independently of billing.
+Use it for a sales evaluation, support compensation, a partner promise, or beta
+access. A pass can be permanent, expire at a deadline, carry named capacity limits,
+and/or have a cumulative usage allowance. These are existing FeatureGrant rows,
+not another subscription system. Available in 0.7.0.
+
+## Issue a sample without replacing a promise
+
+```ruby
+pass = organization.issue_feature_pass!(
+  :distribution,
+  source: "sales_evaluation",
+  note: "Evaluate managed updates; follow up after the first release",
+  expires_at: 3.months.from_now,
+  limits: { storage_bytes: 1.gigabyte, max_artifact_bytes: 200.megabytes },
+  usage_limit: 2.gigabytes
+)
+```
+
+This permits access until the deadline, at most 1 GB stored concurrently, and at
+most 2 GB cumulatively reserved through the write API below. A single artifact
+may be at most 200 MB. The host must supply its live capacity measurements.
+
+`issue_feature_pass!` raises `PricingPlans::FeatureGrantConflict` if there is
+already an active grant for this owner and feature. It never silently shortens
+a permanent grant or replaces a support promise. `source:` is required.
+
+Omit `expires_at` for permanent access. Omit `usage_limit` for no cumulative cap.
+An omitted named limit is unlimited for an entitled feature; a feature with no
+entitlement is still denied. Use `0` to prohibit consumption or a capacity, and
+`:unlimited` explicitly where appropriate. Counts must be nonnegative integers
+within signed bigint range; strings, fractional amounts, negatives, and unknown
+options are rejected by the public pass APIs.
+
+The existing `grant_feature!` remains an upsert. It now accepts `limits:` and
+`usage_limit:` too. When omitted during an upsert, those two settings and consumed
+usage are preserved. Existing semantics for source, note and expiration remain
+unchanged (omitting expiration on that legacy API makes the grant permanent).
+Use the create-only API for an operator's "issue" button.
+
+## Read access and show an offer
+
+```ruby
+organization.plan_allows?(:distribution) # same boolean API as before
+access = organization.feature_access(:distribution)
+access.allowed?          # entitlement exists; does not mean every operation fits
+access.source            # :plan | :grandfather | :grant | nil
+access.grant             # selected grant row, or nil
+access.expires_at        # grant deadline, or nil
+access.limit(:storage_bytes) # integer or :unlimited
+access.usage_count       # cumulative grant consumption
+access.remaining_allowance # integer or :unlimited
+access.available?(amount: upload.bytesize,
+                  usage: { storage_bytes: stored_bytes + upload.bytesize,
+                           max_artifact_bytes: upload.bytesize })
+```
+
+`FeatureAccess` is a snapshot for UI and preflight. Do not cache it across requests
+or use an old snapshot to authorize a write. `available?` returns false on denial;
+`check!` raises `FeatureDenied` or its `FeatureLimitExceeded` subclass, which exposes
+`feature_key`, `plan_owner`, `limit_key`, `allowed`, and `requested`.
+
+Boolean access is intentionally separate from consumption. A fully used upload
+allowance still permits zero-cost operations, such as finalizing or publishing
+an already reserved artifact. A new upload fails when it would exceed the
+allowance. At `expires_at` exactly, the grant is inactive, including for zero-cost
+writes. There is no expiry worker: the next entitlement check sees the deadline.
+
+## Enforce and reserve in the same transaction
+
+```ruby
+organization.with_feature_access!(
+  :distribution,
+  amount: upload.bytesize,
+  usage: -> {
+    {
+      storage_bytes: organization.artifacts.sum(:byte_size) + upload.bytesize,
+      max_artifact_bytes: upload.bytesize
+    }
+  }
+) do |access|
+  organization.artifacts.create!(byte_size: upload.bytesize, filename: upload.filename)
+end
+```
+
+The gem locks a fresh copy of the owner row, resolves access again, reads the
+usage callable, checks the named limits and cumulative allowance, reserves the
+amount, then yields. It bypasses query caches so a preflight read cannot stay
+stale after waiting for a competing writer. It does not reload the caller's
+unsaved attributes. The block's return value is returned.
+Grant consumption is an internal operation;
+use `with_feature_access!`, not a direct counter update, to spend an allowance.
+
+All competing writes must use this API. Capacity values must be measured inside
+the callable, on the owner's database connection. `amount:` and each value in
+`usage:` are separate: the former is cumulative consumption, the latter is the
+prospective capacity after this operation (or its size for a per-operation cap).
+Only the dimensions the host supplies are checked; the gem cannot discover your
+storage system or infer which operation uses a named limit. Declaring `limits:`
+alone does not install callbacks on arbitrary models. Include each applicable
+capacity dimension at its write boundary. Existing association limits continue
+to use their own documented model integration.
+
+The grant update and same-database business write roll back together on an
+exception. A savepoint isolates failure even if an outer transaction rescues it.
+A block that returns false still commits; use bang writes and raise on failure.
+For controller actions that rescue internally, raise `ActiveRecord::Rollback`
+inside the block when the rendered response is unsuccessful. External storage
+and HTTP requests are not database transactions: reserve before handing out an
+upload URL, and define abandoned-upload policy explicitly. Keep lock duration
+short; stream file bytes outside it.
+
+This API does not deduplicate arbitrary operations. Reuse an existing operation
+record/idempotency key before reserving again. Uniqueness violations that escape
+the block roll back consumption. Deleting artifacts does not refund cumulative
+usage. Use live stored capacity when deletions should free room. The allowance
+belongs to this grant lifecycle, with no periodic reset, transferable balance,
+refund API, or purchase ledger; use `usage_credits` for a credit economy.
+
+Row-level concurrency guarantees require a database such as PostgreSQL or MySQL.
+SQLite does not provide equivalent row locks. Owners and grants must use the
+same database/connection for atomicity. Direct SQL, `update_columns`, and writes
+that bypass this API are outside the contract.
+
+## Paid access wins
+
+Precedence remains plan, then qualifying grandfather, then active grant. A paid
+plan's access never spends or inherits a pass's allowance, and a pass never
+restricts an owner whose plan already carries the feature. Named limits belong
+to the pass alone: plan and grandfather access carry none, so `limit(:key)`
+answers `:unlimited` for them and your app keeps owning its plan quotas exactly
+as it did before passes existed. Limits do not stack and are not merged between
+sources. If the owner later downgrades, an unexpired, unrevoked pass resumes
+with its previous consumed usage. Buying a plan does not delete the pass. A plan
+that merely has a higher price does not win unless it actually allows the feature.
+
+## Revise or revoke explicitly
+
+```ruby
+pass.revise!(expires_at: 6.months.from_now, usage_limit: 4.gigabytes,
+             note: "Customer requested time for the next release")
+organization.revoke_feature!(:distribution, note: "Evaluation ended early")
+organization.feature_grants # retained active, expired, and revoked lifecycles
+```
+
+`revise!` accepts only `expires_at`, `limits`, `usage_limit`, and `note`, preserves
+consumption, and refuses expired/revoked rows. Lowering the allowance below used
+usage blocks further consumption; it does not rewrite history. Passing nil to
+`usage_limit` removes that cap. Passing `{}` to `limits` clears named caps.
+
+Revocation is serialized with consumption. Revoking a grant cannot remove plan
+or grandfather access. Issue a new pass after expiry/revocation for a new
+allowance and history row. The table retains lifecycle history, not an immutable
+log of every edit: revisions and legacy upserts update their row. Apps should
+record the operator and reason, and append change notes or use their audit system.
+
+## Installation and backwards compatibility
+
+| Starting point | Command |
+| --- | --- |
+| New app | `rails generate pricing_plans:install` |
+| App without feature grants (before 0.6.0) | `rails generate pricing_plans:grants` |
+| App with the 0.6.x grants table | `rails generate pricing_plans:passes` |
+
+Then run `rails db:migrate`. Run only the applicable generator, not all three.
+The additive upgrade adds JSON `limits` (default `{}`), nullable bigint
+`usage_limit`, bigint `usage_count` (default `0`), and a nonnegative usage check.
+It does not alter owners, existing expirations, revocations, or billing rows.
+Existing grants remain unbounded unless the app deliberately supplies a policy.
+
+Old-schema boolean grants continue to work after upgrading gem code. New
+capacity/consumption writes raise an actionable migration error before doing work
+if the pass columns are missing. Deploy the schema before enabling pass UI and
+metered write paths. No destructive backfill or scheduled expiry job is needed.
+
+## A complete SaaS offering
+
+The gem owns entitlement resolution, capacity comparison, deadlines, consumption,
+locking, and lifecycle APIs. The app owns authenticated operator controls,
+allowed feature/metric choices, units, emails, customer wording, pricing links,
+and storage measurements. Never present an editable metric the app does not
+actually enforce. An organization-owned SaaS should grant to the organization,
+not a member's User record; a user-owned SaaS can include PlanOwner on User.
+
+For distribution, a useful default is to block new uploads/publishing at expiry
+while continuing to serve existing feeds and downloads. Enforce this by putting
+gates on write endpoints only. Do not delete customer data as an expiry side
+effect. Explain the deadline and paid continuation option before the evaluation.
+A whole-plan Stripe trial or expiring plan override is a separate product:
+feature passes do not create trials, change subscriptions, or expire assignments.