Browse pages
Plans and Entitlements
A product that gates behavior and amounts by tier records each plan's entitlements in one place: the behavior the plan unlocks and the amounts it allows. This page states how the product records its plans, how behavior and amounts resolve to what the acting plan entitles, and how the product answers a run past its plan. A project selects it when tiers change what the software allows, so a plan change moves one record instead of scattered checks.
Stack: any
Layer: application
Activation#
Activation scope: project.
Applicable specification kinds: None.
The project selects plans when tiers gate behavior or amounts in the software, within one offering or across several. An offering with no gated behavior or amount does not select it: without gated tiers there is nothing to entitle.
Baseline Relationship#
This extension replaces no baseline provision. It sits beside the multitenancy extension: tenancy isolates each tenant's data, while plans state what each tenant's tier allows.
It switches on no record type: plans live as policy requirements, gated behavior resolves through permissions, and gated amounts resolve through settings, which the intent page, the access page, and the behavior page state.
Standards#
Record Each Plan Once#
ruleruleguidancelitespec/ext/plans#record-each-plan-onceA consumer selecting plans MUST record each plan once with its name and entitlements.
Applies toartifact: record:requirement
Why
A plan named in two places disagrees the day one updates without the other: one record promises what the gate refuses. One record per plan holds the name and the entitlements, so a plan change is one edit in one place.
Example
The team tier names the export use case and the row cap it unlocks.
Checka reviewer answers
Reviewed forThe requirement pages under .litespec/intent/ hold one record per plan with its entitlements.
Marked guidance: a reviewer answers this question.
Gate Behavior Through Permissions#
ruleruleguidancelitespec/ext/plans#gate-behavior-through-permissionsA gated use case MUST declare a permission that only an entitled plan grants.
Applies toartifact: record:use-case
Why
The permission chain already joins actors to use cases: the actor holds a role, the role allows a permission, and the use case declares it in its grant, as the access page states. A plan grants its permissions through that chain, so entitlement is a grant like any other instead of a second access system beside the first.
Checka reviewer answers
Reviewed forEach gated use case declares a permission in its grant that only an entitled plan grants.
Marked guidance: a reviewer answers this question.
Bound Plan Amounts in Settings#
ruleruleguidancelitespec/ext/plans#bound-plan-amounts-in-settingsEach amount a plan allows MUST live as a setting the gated use case cites.
Applies toartifact: record:setting-set
Why
An allowance buried in code changes only with a release, and each plan's number hides in a different branch. A setting states the range, the setter, and the bound behavior, and the gated use case cites it, so raising a tier edits the setting instead of the code. litespec/core/access#cite-the-setting-or-plan-behind-every-entitlement requires the citation, and litespec/core/use-cases#hold-every-setting-default-to-a-requirement holds a commercial default to its requirement.
Example
The export-row cap lives as setting/spending.max-export-rows with an operator-set value, and the export command cites it.
Checka reviewer answers
Reviewed forEach plan allowance lives as a setting the gated use case cites.
Marked guidance: a reviewer answers this question.
Refuse Runs Beyond Entitlement#
ruleruleguidancelitespec/ext/plans#refuse-runs-beyond-entitlementA use case run past its plan MUST end in the refusal result the use case names for that run.
Applies toartifact: record:use-case
Why
A run past its plan is a refusal like any other: it ends in the named refusal result with its stable code, as the behavior page states, so callers branch on one code instead of guessing from an error page. The code stays stable while prices and allowances move.
Checka reviewer answers
Reviewed forA run past its plan ends in the named refusal result in the use case tests.
Marked guidance: a reviewer answers this question.
Resolve the Acting Plan from Trusted Context#
ruleruleguidancelitespec/ext/plans#resolve-the-acting-plan-from-trusted-contextThe product MUST resolve the acting plan from verified subscription state, never from caller input.
Applies toartifact: any
Why
The plan decides what runs, so only verified subscription state resolves it: a plan the caller supplies itself is a choice, not a fact. The multitenancy extension treats tenant identity the same way.
Checka reviewer answers
Reviewed forThe acting plan resolves from verified subscription state, with no plan taken from caller input in code.
Marked guidance: a reviewer answers this question.
Hide Unentitled Actions on Screens#
ruleruleguidancelitespec/ext/plans#hide-unentitled-actions-on-screensA screen MUST NOT offer an action the acting plan does not entitle.
Applies toartifact: record:screen
Why
The server refuses what the plan does not entitle, and the screen reflects that refusal before the call: a button for an unentitled action invites a failure the product already decided. Hiding or disabling the action shows each plan only what it may run.
Checka reviewer answers
Reviewed forEach screen shows only actions the acting plan entitles.
Marked guidance: a reviewer answers this question.
Conventions#
Resolve the Acting Plan in the Authorization Pipeline#
conventiondefaultguidancelitespec/ext/plans#resolve-the-acting-plan-in-the-authorization-pipelineResolve the acting plan where the pipeline authorizes the use case.
ReplacementA consumer records a plan-resolution convention naming where its use cases find the acting plan.
Applies toartifact: any
Why
Authorization already runs in the pipeline with the actor and the target in hand. Resolving the plan there gives every use case the same answer from the same verified state, instead of each handler querying subscriptions its own way.
Checka reviewer answers
Reviewed forThe authorization pipeline resolves the acting plan, or the plan-resolution convention names where use cases find it.
Marked guidance: a reviewer answers this question.
Dependencies#
Packages: None.
Related extensions: The tenancy extension owns tenant isolation when tenants sit on different tiers. The audit extension owns tamper-resistant evidence when an entitlement decision needs a record.
Guides: None.