Plan and Entitlement Model

1) The problem this lesson solves

In many SaaS products, the commercial plan name, billing Product/Price identity, and actual application access live in separate systems. Treating them as one record lets a price change silently alter access semantics or turns a temporary exception into permanent hidden access.

2) Lesson boundary and deliverable

The deliverable is Plan-to-Entitlement Contract v1. ARC-020 does not own ARC-019 P&L per Client or ARC-021 SLA/Support Model, and it performs no live billing, subscription, tenant, or authorization mutation.

3) Fact: billing entitlements can represent feature access

Stripe Entitlements is designed to determine when product feature access can be granted or revoked. It is an official product example of separating capability access from a commercial display label; it does not define MAKNOW taxonomy or authorization policy.

4) Fact: Product and Price are not the entitlement

Stripe uses Product for what is sold and Price for how much/how often it is charged. Its recurring pricing documentation includes flat-rate, per-seat, tiered, and usage-based models. Those objects alone do not prove what the runtime should grant.

5) Use the right mental model: Commercial Authority → Entitlement → Runtime

The baseline flow is plan/product/price/subscription → entitlement mapping → feature grant/limit → runtime snapshot → reconciliation. Never use a display plan name as the application permission key.

6) Build the contract with stable identities

Record plan_id, product_id, price_id, entitlement_id, and feature_key separately. If price changes but the entitlement mapping remains on the old authority, return DRIFT rather than silently succeeding.

7) Separate Grant from Limit

grant_state says whether a feature should be active. limit_type and limit_value state capacity semantics. Boolean access, seat limits, and metered allowances are different contracts and must not collapse into one ambiguous number.

8) Metering needs an authority reference

When limit_type=METERED, meter_ref must exist. A metered feature without a meter authority cannot be reconciled and remains HOLD.

9) Effective windows are decisive

effective_from and effective_to bound entitlement or exception validity. Access outside a valid window must be investigated as drift/revocation rather than treated as correct because the runtime still serves it.

10) Do not turn a temporary override into hidden debt

Every override needs an ID, owner, reason, and expiry. A valid bounded exception may produce OVERRIDE; once the window expires, excess runtime access must produce REVOKE.

11) Make revocation triggers explicit

Subscription states such as unpaid or canceled become access-control evidence when local policy names them as revocation triggers. Reconcile those triggers against the runtime snapshot instead of assuming billing and access converge automatically.

12) Core Evidence Contract

This lesson uses 20 evidence dimensions, 16 of them critical. The table below compresses baseline, stale-mapping, and transfer states; CSV/JSON preserve the full mapping.

13) Typed states prevent fake success

ALIGNED, DRIFT, OVERRIDE, REVOKE, and HOLD are all legitimate outputs. Missing decisive evidence must never be guessed into ALIGNED.

14) Reconciliation is a recurring gate

A change in Price, Plan, limit, meter, subscription state, or override window should trigger review/reconciliation. The runtime snapshot is observation; authority comes from the commercial contract and entitlement mapping.

15) Lab, transfer, and freshness

The lab uses eight fixtures and 48 assertions. In transfer, a customer downgrades at renewal, keeps an approved seven-day seat override, and one feature moves from flat to metered. The learner recomputes from the changed evidence. Stripe documentation remains external FACT; thresholds, state vocabulary, and override policy remain MAKNOW DESIGN.