AI SaaS Runtime Entitlement Snapshots: Keeping Long Tasks, Authorization, and Cache Consistent

A user just upgraded to Pro and the frontend shows success, yet the model gateway still rejects them as Free; another user downgraded but an Agent queued for two hours keeps using the advanced model; out-of-order Webhooks overwrite the new plan back to the old state. These problems are not simply "slow cache refresh"; they happen because the system has not defined which subscription fact produces which entitlements at what time, and which version a run should bind to.

AI Pricing Migration handles contracts, prices, cohorts, and billing schedules, and AI Platform Tenant Quota enforces resource limits. This article only owns the entitlement control plane: it consumes effective commercial facts and projects them into runtime authorization snapshots such as model, context, concurrency, export, and support levels.

Plans and Entitlements Both Use Immutable Versions

Do not modify the pro row and make all historical customers change instantly. Each commercial definition change creates a new planVersion, listing features, model tiers, included units, overage policy, concurrency, context cap, data retention, and support entitlements. Subscription instances reference the version and record effectiveFrom/effectiveTo, trials, add-ons, grandfather cohorts, and manual overrides.

{
  "snapshotId": "ent_01J...",
  "accountId": "ac_42",
  "revision": 184,
  "planVersion": "pro-2026-07",
  "effectiveAt": "2026-08-01T00:00:00Z",
  "features": {
    "modelTier": "advanced",
    "monthlyIncludedUnits": "500000",
    "maxConcurrentRuns": 5,
    "dataExport": true
  },
  "source": { "subscriptionId": "sub_9", "eventId": "evt_7" },
  "policyDigest": "sha256:..."
}

Entitlement quantities use integer units; currency and price are not stuffed into the runtime snapshot. An override must have a reason, approver, and expiration; it cannot become a permanent hidden plan. The merge order of plan, subscription, add-on, and override is fixed and versioned; identical inputs must produce the same snapshot hash.

Webhooks Are Notifications, Not an Ordered Fact Stream

Billing platforms may deliver events duplicated, delayed, or out of order. The consumer deduplicates by the provider event ID; after receiving a notification, it reads or verifies the current subscription object, then a local transaction generates a monotonically increasing revision; an older effective time or older source state cannot overwrite a newer snapshot. Immediate upgrade, end-of-term downgrade, pause, cancellation, and trial expiry each get an explicit effective point, rather than "the last received event wins".

Writing subscription state, the entitlement snapshot, and the cache invalidation outbox belong to the same transaction. The downstream cache key is (accountId, revision), not just the account ID with an arbitrary TTL. Duplicate invalidation messages are harmless; once a node observes revision 184, it refuses to apply 183. If subscription sync fails, high-risk paid write features fail closed; briefly retaining last-known read entitlements must have a maximum staleness and an alert.

Requests and Long Tasks Explicitly Bind to a Snapshot

The gateway resolves the snapshot from a trusted account context, and does not accept client self-reported plan=pro. Each operation stores the entitlementRevision, plan version, and policy digest; the executor verifies features and limits before creating resources. Regular requests pin the snapshot at the start, preventing a streaming response from changing the model or pricing basis midway.

Long tasks need the rules split: committed billing units, model tier, and output cap usually bind to the admission snapshot; safety bans, account suspension, and permission revocation take effect in real time; whether a plan downgrade allows running tasks to complete must be explicit in the contract. When a task resumes, load the original revision and also query live revocation; you must not read only a stale JWT. The checkpoints of Long-Task Agent Workflows should persist both versions.

After an upgrade, new operations can immediately use the new entitlements; for a downgrade effective at end of term, the new snapshot is created in advance but only activates at effectiveAt. Clocks are unified to UTC, and boundary comparison is done server-side. When a run spans billing periods, actual usage is still settled by the event time and the bound contract; you cannot, for implementation convenience, attribute everything to the end day.

Intersect Entitlements with Feature Flags

Entitlements answer "what the customer purchased", and feature flags answer "whether the code is released to this group of users". The final allow condition should be entitled && rollout_enabled && policy_allowed. An OpenFeature provider can carry the rollout, but a flag cannot grant an unpurchased feature to a random experiment bucket, nor delete a customer's contractual entitlement when rolling back the UI. The experiment context of AI Feature Flags also needs to include the snapshot revision, to explain why the same account yields different results.

Metrics record a limited plan version, feature, decision, and stale class, and do not use account ID as a label. Audit stores the input revision, merge rules, decision, cache node, and operation ID, so customer service can answer whether a given rejection came from not-purchased, not-released, quota-exhausted, or a security policy.

Validate with Out-of-Order and Time Boundaries

Test duplicate Webhooks, cancellation followed by an old upgrade, end-of-term schedules, trial expiry, override expiry, cache nodes offline, tasks spanning a downgrade, account bans, and rollback to an old policy. Assert that the revision still increments during rollback, only one snapshot is active at any moment, flags cannot exceed entitlements, and bound operations do not drift in their pricing basis. Replay the entire subscription cycle with a fixed clock, rather than waiting for real months.

A new resolver first computes decisions in shadow and compares request-by-request with the old system; switch by feature, not by replacing all entitlements at once. On exceptions, you can restore the old resolver image, but snapshot aliases never go backward: append a higher revision, point the policy body at the last approved version, record supersedes, the new effectiveAt, and the rollback reason, then publish through the normal outbox. Generated history is not deleted, and live revocations cannot be undone by a commercial rollback either. An incorrectly scheduled plan change should be cancelled from the schedule or have a correction version appended, not tampered with in place. The goal of entitlement consistency is not for all caches to be identical in an instant, but for every decision to point to a single, valid, and monotonically evolving commercial snapshot.

Further Reading

• AI Product Pricing Models
• AI Feature Flag
• AI Platform Tenant Quota
• Long-Task Agent Workflows