pricing_plans 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6b80d22fc74b3afafd8f850f0bbe401c9af56d9dad8102233c48e4e332f1b62
-  data.tar.gz: a03538e62a477cb3ba9f90df6e27de51a48d7b348f2aef96dd7cca0dd997bf88
+  metadata.gz: 69a00b6a4bbe7bc513e707744b890a0fbcea4161f322f5a5d3384ae1775be130
+  data.tar.gz: 6647732b7368f398bb62eaa1968af7b0132ef68f2ad89f858aa507922c794e4d
 SHA512:
-  metadata.gz: 605f1beb4fdc85b9b8b26b2e8da96fb620f9b8bd28ecadf4688d5b00cf002aaa979155abeccef100f50e3a9b9932095506b691e0bbd84f4727f0cebdaaba40bd
-  data.tar.gz: 3b8ecc71305850c3760d3a96ee530c2069a099806733223280b834cd368fbe9773d8483f5a7fa02744fd0704206d6a142a0933d8837133c28ca85a93fc0d1860
+  metadata.gz: f77dce78f0d0fa86cd195f6b7fab99992634cb17ed5543973fbb3afa0774da80ed1236ea5cb712df1e2b9e58bb2925c7a476942f8aab0720926332c3cbc89a35
+  data.tar.gz: 42add5c893313c1dddbbe7af5c54882872e6d75b6551d70c074e5e44ed96e54be72e778b40e7aacbb5daf222499b0ff7d208f165d42c766b9fb62217b79e5a0a

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [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.**

data/README.md

@@ -279,6 +279,22 @@ 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/07-repricing.md

@@ -96,3 +96,8 @@ org.pricing_relationship_started_at
 [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.

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

@@ -10,11 +10,18 @@ class CreatePricingPlansFeatureGrants < ActiveRecord::Migration<%= migration_ver
       t.string :source, null: false
       t.text :note
       t.datetime :expires_at
+      t.send(json_column_type, :limits, default: {}, null: false)
+      t.bigint :usage_limit
+      t.bigint :usage_count, default: 0, null: false
       t.datetime :revoked_at
 
       t.timestamps
     end
 
+    add_check_constraint :pricing_plans_feature_grants,
+                         "usage_count >= 0 AND (usage_limit IS NULL OR usage_limit >= 0)",
+                         name: "pricing_plans_feature_pass_usage_nonnegative"
+
     add_index :pricing_plans_feature_grants,
               [ :plan_owner_type, :plan_owner_id, :feature_key ],
               name: "idx_pricing_plans_feature_grants_lookup"
@@ -29,4 +36,9 @@ class CreatePricingPlansFeatureGrants < ActiveRecord::Migration<%= migration_ver
     foreign_key_type = setting || :bigint
     [ primary_key_type, foreign_key_type ]
   end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+    :json
+  end
 end

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

@@ -77,11 +77,18 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
       t.string :source, null: false
       t.text :note
       t.datetime :expires_at
+      t.send(json_column_type, :limits, default: {}, null: false)
+      t.bigint :usage_limit
+      t.bigint :usage_count, default: 0, null: false
       t.datetime :revoked_at
 
       t.timestamps
     end
 
+    add_check_constraint :pricing_plans_feature_grants,
+                         "usage_count >= 0 AND (usage_limit IS NULL OR usage_limit >= 0)",
+                         name: "pricing_plans_feature_pass_usage_nonnegative"
+
     add_index :pricing_plans_feature_grants,
               [ :plan_owner_type, :plan_owner_id, :feature_key ],
               name: "idx_pricing_plans_feature_grants_lookup"

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

@@ -147,3 +147,8 @@ PricingPlans.configure do |config|
   # When set to true, detailed debug output will be printed to stdout, which can be helpful for troubleshooting.
   # config.debug = false
 end
+
+# Individual sales evaluations (after migration; run from your app/admin service):
+# owner.issue_feature_pass!(:api_access, source: "sales", expires_at: 3.months.from_now)
+# Capacity/consumption offers require with_feature_access! at the write boundary.
+# Full guide: https://github.com/rameerez/pricing_plans/blob/main/docs/08-feature-passes.md

data/lib/generators/pricing_plans/passes/passes_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module PricingPlans
+  module Generators
+    class PassesGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Add capacity limits and cumulative usage to existing feature grants"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "add_feature_pass_limits.rb.erb",
+                           File.join(db_migrate_path, "add_feature_pass_limits.rb"),
+                           migration_version: migration_version
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/pricing_plans/passes/templates/add_feature_pass_limits.rb.erb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class AddFeaturePassLimits < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :pricing_plans_feature_grants, :limits, json_column_type, default: {}, null: false
+    add_column :pricing_plans_feature_grants, :usage_limit, :bigint
+    add_column :pricing_plans_feature_grants, :usage_count, :bigint, default: 0, null: false
+    add_check_constraint :pricing_plans_feature_grants,
+                         "usage_count >= 0 AND (usage_limit IS NULL OR usage_limit >= 0)",
+                         name: "pricing_plans_feature_pass_usage_nonnegative"
+  end
+
+  private
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+    :json
+  end
+end

data/lib/pricing_plans/feature_access.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class FeatureGrantConflict < Error; end
+
+  class FeatureLimitExceeded < FeatureDenied
+    attr_reader :limit_key, :allowed, :requested
+
+    def initialize(feature_key:, plan_owner:, limit_key:, allowed:, requested:)
+      @limit_key = limit_key
+      @allowed = allowed
+      @requested = requested
+      super("#{feature_key.to_s.humanize}: #{limit_key.to_s.humanize.downcase} limit exceeded " \
+            "(#{requested} requested, #{allowed} allowed).", feature_key: feature_key, plan_owner: plan_owner)
+    end
+  end
+
+  # One snapshot for presentation and preflight checks. Writes must use
+  # PlanOwner#with_feature_access! to resolve again under the owner row lock.
+  class FeatureAccess
+    MAX_INTEGER = (2**63) - 1
+    attr_reader :owner, :feature_key, :source, :grant, :limits
+
+    def self.validate_amount!(amount)
+      return amount if amount.is_a?(Integer) && amount.between?(0, MAX_INTEGER)
+
+      raise ArgumentError, "usage must be a nonnegative integer no larger than #{MAX_INTEGER}"
+    end
+
+    def self.normalize_limits(limits)
+      raise ArgumentError, "limits must be a Hash" unless limits.is_a?(Hash)
+
+      limits.each_with_object({}) do |(key, amount), result|
+        unless (key.is_a?(String) || key.is_a?(Symbol)) && key.to_s.match?(/\A[a-z][a-z0-9_]*\z/)
+          raise ArgumentError, "limit keys must be lowercase names such as storage_bytes"
+        end
+        raise ArgumentError, "duplicate limit #{key}" if result.key?(key.to_s)
+
+        result[key.to_s] = if amount == :unlimited || amount == "unlimited"
+                             "unlimited"
+                           else
+                             validate_amount!(amount)
+                           end
+      end
+    end
+
+    # Named limits belong to a pass. Plan and grandfather access carry none:
+    # the gem answers "is this owner entitled?", and the app owns its plan
+    # quotas the way it always has.
+    def initialize(owner, feature_key)
+      @owner = owner
+      @feature_key = feature_key.to_sym
+      @source = owner.feature_entitlement_source(@feature_key)
+      @grant = owner.feature_grants.active.for_feature(@feature_key).first if source == :grant
+      @source = nil if source == :grant && !grant
+      @limits = (grant ? grant.pass_limits : {}).freeze
+    end
+
+    def allowed? = !source.nil?
+    def expires_at = grant&.expires_at
+    def usage_limit = grant&.pass_usage_limit
+    def usage_count = grant ? grant.pass_usage_count : 0
+
+    def limit(key)
+      value = limits.fetch(key.to_s, "unlimited")
+      value == "unlimited" ? :unlimited : value
+    end
+
+    def remaining_allowance
+      usage_limit ? [usage_limit - usage_count, 0].max : :unlimited
+    end
+
+    def available?(amount: 0, usage: {})
+      check!(amount: amount, usage: usage)
+      true
+    rescue FeatureDenied
+      false
+    end
+
+    def check!(amount: 0, usage: {})
+      self.class.validate_amount!(amount)
+      raise ArgumentError, "usage must be a Hash" unless usage.is_a?(Hash)
+
+      unless allowed?
+        raise FeatureDenied.new("#{feature_key.to_s.humanize} is not available.",
+                                feature_key: feature_key, plan_owner: owner)
+      end
+
+      check_capacity!(usage)
+      check_limit!(:usage, usage_limit, usage_count + amount) if usage_limit && amount.positive?
+      self
+    end
+
+    private
+
+    def check_capacity!(usage)
+      usage.each do |key, value|
+        self.class.validate_amount!(value)
+        check_limit!(key.to_sym, limit(key), value)
+      end
+    end
+
+    def check_limit!(key, allowed, requested)
+      return if allowed == :unlimited || requested <= allowed
+
+      raise FeatureLimitExceeded.new(feature_key: feature_key, plan_owner: owner,
+                                     limit_key: key, allowed: allowed, requested: requested)
+    end
+  end
+end

data/lib/pricing_plans/models/feature_grant.rb

@@ -18,6 +18,7 @@ module PricingPlans
     validates :feature_key, presence: true
     validates :source, presence: true
     validate :expires_at_must_be_parseable
+    validate :pass_options_must_be_valid
 
     scope :for_feature, ->(feature_key) { where(feature_key: feature_key.to_s) }
     scope :active, lambda {
@@ -29,18 +30,67 @@ module PricingPlans
     end
 
     def revoke!(note: nil)
-      return self if revoked_at.present?
+      self.class.with_owner_lock(plan_owner) do
+        reload
+        update!(revoked_at: Time.current, note: [self.note, note].compact.presence&.join(" | ")) unless revoked_at.present?
+      end
+      self
+    end
+
+    def pass_limits
+      has_attribute?(:limits) ? FeatureAccess.normalize_limits(self[:limits] || {}) : {}
+    end
 
-      update!(revoked_at: Time.current, note: [self.note, note].compact.presence&.join(" | "))
+    def pass_usage_limit = has_attribute?(:usage_limit) ? self[:usage_limit] : nil
+    def pass_usage_count = has_attribute?(:usage_count) ? self[:usage_count] : 0
+
+    # Internal to PlanOwner#with_feature_access!, which calls this on a row it
+    # loaded fresh under the owner lock after FeatureAccess#check! passed. The
+    # lock is what makes check-then-increment safe; this method neither
+    # re-acquires it nor reloads. Keep this private: the database constraint
+    # rejects negative counters, but cannot enforce the allowance or expiry.
+    def record_usage!(amount)
+      self.class.ensure_pass_columns!
+      FeatureAccess.validate_amount!(amount)
+      raise FeatureDenied, "This feature pass is no longer active." unless active?
+
+      total = pass_usage_count + amount
+      FeatureAccess.validate_amount!(total)
+      if pass_usage_limit && total > pass_usage_limit
+        raise FeatureLimitExceeded.new(feature_key: feature_key, plan_owner: plan_owner,
+                                       limit_key: :usage, allowed: pass_usage_limit, requested: total)
+      end
+
+      increment!(:usage_count, amount, touch: true)
+    end
+    private :record_usage!
+
+    # Revise a specific lifecycle without resetting consumption or resurrecting it.
+    def revise!(**options)
+      unknown = options.keys - [:expires_at, :note, :limits, :usage_limit]
+      raise ArgumentError, "unknown revision options: #{unknown.join(', ')}" if unknown.any?
+      self.class.ensure_pass_columns! if (options.keys & [:limits, :usage_limit]).any?
+      self.class.with_owner_lock(plan_owner) do
+        reload
+        raise FeatureGrantConflict, "This pass is no longer active; issue a new pass." unless active?
+        options[:limits] = FeatureAccess.normalize_limits(options[:limits]) if options.key?(:limits)
+        FeatureAccess.validate_amount!(options[:usage_limit]) if options.key?(:usage_limit) && !options[:usage_limit].nil?
+        update!(**options)
+      end
       self
     end
 
     class << self
       # Idempotent: updates the active grant for (owner, feature) if one
       # exists, otherwise creates it. Revoked grants stay behind as history.
-      def grant_to!(plan_owner, feature_key, source: "manual", note: nil, expires_at: nil)
+      def grant_to!(plan_owner, feature_key, source: "manual", note: nil, expires_at: nil, replace: true, **options)
         ensure_table!
         ensure_persisted_owner!(plan_owner)
+        unknown = options.keys - [:limits, :usage_limit]
+        raise ArgumentError, "unknown pass options: #{unknown.join(', ')}" if unknown.any?
+        ensure_pass_columns! if options.any?
+        options[:limits] = FeatureAccess.normalize_limits(options[:limits]) if options.key?(:limits)
+        FeatureAccess.validate_amount!(options[:usage_limit]) if options.key?(:usage_limit) && !options[:usage_limit].nil?
 
         # Serialize grant writes through the owner row. A lookup followed by
         # create is otherwise race-prone, and a portable partial unique index
@@ -49,7 +99,8 @@ module PricingPlans
         with_locked_owner(plan_owner) do
           grant = active.find_by(owner_conditions(plan_owner).merge(feature_key: feature_key.to_s))
           if grant
-            grant.update!(source: source.to_s, note: note, expires_at: expires_at)
+            raise FeatureGrantConflict, "An active grant already exists for #{feature_key}; revise it explicitly." unless replace
+            grant.update!(source: source.to_s, note: note, expires_at: expires_at, **options)
             grant
           else
             create!(
@@ -57,7 +108,8 @@ module PricingPlans
               feature_key: feature_key.to_s,
               source: source.to_s,
               note: note,
-              expires_at: expires_at
+              expires_at: expires_at,
+              **options
             )
           end
         end
@@ -91,6 +143,17 @@ module PricingPlans
         false
       end
 
+      def ensure_pass_columns!
+        return if %w[limits usage_limit usage_count].all? { |name| column_names.include?(name) }
+
+        raise ConfigurationError, "Run `rails generate pricing_plans:passes && rails db:migrate` to add feature pass limits."
+      end
+
+      def with_owner_lock(plan_owner, &block)
+        ensure_persisted_owner!(plan_owner)
+        with_locked_owner(plan_owner, &block)
+      end
+
       private
 
       def ensure_table!
@@ -117,17 +180,27 @@ module PricingPlans
       def with_locked_owner(plan_owner)
         owner_class = plan_owner.class.base_class
 
-        owner_class.transaction do
-          # Lock a fresh copy so granting a feature never reloads or rejects a
-          # caller that happens to have unrelated unsaved changes.
-          owner_class.unscoped.lock.find(plan_owner.id)
-          yield
+        owner_class.uncached do
+          owner_class.transaction(requires_new: true) do
+            # Lock a fresh copy without changing the caller's unsaved attributes.
+            # Bypass preflight query caches after waiting for another writer.
+            owner_class.unscoped.lock.find(plan_owner.id)
+            yield
+          end
         end
       end
     end
 
     private
 
+    def pass_options_must_be_valid
+      pass_limits
+      FeatureAccess.validate_amount!(pass_usage_count)
+      FeatureAccess.validate_amount!(pass_usage_limit) unless pass_usage_limit.nil?
+    rescue ArgumentError => error
+      errors.add(:base, error.message)
+    end
+
     def expires_at_must_be_parseable
       raw_value = expires_at_before_type_cast
       return if raw_value.nil? || (raw_value.is_a?(String) && raw_value.blank?)

data/lib/pricing_plans/plan.rb

@@ -182,6 +182,11 @@ module PricingPlans
     # Feature methods
     def allows(*feature_keys)
       feature_keys.flatten.each do |key|
+        unless key.is_a?(Symbol) || key.is_a?(String)
+          raise ConfigurationError,
+                "`allows` takes feature names only (got #{key.inspect}). Plan quotas live in " \
+                "`limits`; per-owner capacities live on feature passes (`issue_feature_pass!(..., limits: {})`)."
+        end
         @features.add(key.to_sym)
       end
     end

data/lib/pricing_plans/plan_owner.rb

@@ -308,8 +308,32 @@ module PricingPlans
     # Per-owner feature grants: individual, auditable exceptions on top of
     # plan resolution (comps, beta access, sales exceptions, promises that
     # must survive cancellation). See PricingPlans::FeatureGrant.
-    def grant_feature!(feature_key, source: "manual", note: nil, expires_at: nil)
-      FeatureGrant.grant_to!(self, feature_key, source: source, note: note, expires_at: expires_at)
+    def grant_feature!(feature_key, source: "manual", note: nil, expires_at: nil, **options)
+      FeatureGrant.grant_to!(self, feature_key, source: source, note: note, expires_at: expires_at, **options)
+    end
+
+    # Create-only sales/support pass: never replace an existing customer promise.
+    def issue_feature_pass!(feature_key, source:, **options)
+      FeatureGrant.grant_to!(self, feature_key, source: source, **options, replace: false)
+    end
+
+    def feature_access(feature_key)
+      FeatureAccess.new(self, feature_key)
+    end
+
+    # The block and cumulative reservation share a transaction. Read live capacity
+    # in the usage callable, after locking; do not pass a precomputed count.
+    # All competing writers must use this API and the owner's database connection.
+    def with_feature_access!(feature_key, amount: 0, usage: -> { {} })
+      raise ArgumentError, "a block is required" unless block_given?
+      raise ArgumentError, "usage must be callable so it is read under the lock" unless usage.respond_to?(:call)
+      FeatureAccess.validate_amount!(amount)
+      FeatureGrant.with_owner_lock(self) do
+        access = feature_access(feature_key)
+        access.check!(amount: amount, usage: usage.call)
+        access.grant.__send__(:record_usage!, amount) if access.grant && amount.positive?
+        yield access
+      end
     end
 
     # Revokes active grants for the feature (audit rows are kept, stamped

data/lib/pricing_plans/version.rb

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

data/lib/pricing_plans.rb

@@ -30,6 +30,9 @@ module PricingPlans
   end
   class InvalidOperation < Error; end
 
+  autoload :FeatureAccess, "pricing_plans/feature_access"
+  autoload :FeatureLimitExceeded, "pricing_plans/feature_access"
+  autoload :FeatureGrantConflict, "pricing_plans/feature_access"
   autoload :Configuration, "pricing_plans/configuration"
   autoload :Registry, "pricing_plans/registry"
   autoload :Plan, "pricing_plans/plan"
@@ -75,7 +78,7 @@ module PricingPlans
     # warnings independently and lets Rails include them in its deprecator
     # collection.
     def deprecator
-      @deprecator ||= ActiveSupport::Deprecation.new("0.7.0", "pricing_plans")
+      @deprecator ||= ActiveSupport::Deprecation.new("0.8.0", "pricing_plans")
     end
 
     def configure(&block)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pricing_plans
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -78,6 +78,7 @@ files:
 - docs/05-semantic-pricing.md
 - docs/06-gem-compatibility.md
 - docs/07-repricing.md
+- docs/08-feature-passes.md
 - docs/images/pricing_plans_ruby_rails_gem_pricing_table.jpg
 - docs/images/pricing_plans_ruby_rails_gem_usage_alert_upgrade.jpg
 - docs/images/pricing_plans_ruby_rails_gem_usage_meter.jpg
@@ -90,6 +91,8 @@ files:
 - lib/generators/pricing_plans/install/install_generator.rb
 - lib/generators/pricing_plans/install/templates/create_pricing_plans_tables.rb.erb
 - lib/generators/pricing_plans/install/templates/initializer.rb
+- lib/generators/pricing_plans/passes/passes_generator.rb
+- lib/generators/pricing_plans/passes/templates/add_feature_pass_limits.rb.erb
 - lib/pricing_plans.rb
 - lib/pricing_plans/association_limit_registry.rb
 - lib/pricing_plans/callbacks.rb
@@ -99,6 +102,7 @@ files:
 - lib/pricing_plans/dsl.rb
 - lib/pricing_plans/engine.rb
 - lib/pricing_plans/exceeded_state_utils.rb
+- lib/pricing_plans/feature_access.rb
 - lib/pricing_plans/grace_manager.rb
 - lib/pricing_plans/integer_refinements.rb
 - lib/pricing_plans/job_guards.rb
@@ -129,7 +133,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/rameerez/pricing_plans
-  source_code_uri: https://github.com/rameerez/pricing_plans/tree/v0.6.0
+  source_code_uri: https://github.com/rameerez/pricing_plans/tree/v0.7.0
   changelog_uri: https://github.com/rameerez/pricing_plans/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/rameerez/pricing_plans/issues
   documentation_uri: https://github.com/rameerez/pricing_plans#readme