Entitlement Plan Source Extraction Protocol

Candidate: entitlement-plan-source

Target owner: cloudflare-saas-core

Target package: cloudflare-saas-core/packages/entitlements

Purpose

This protocol freezes the shared contract for server-side entitlement decisions and audited plan-source writes before entitlement code moves out of this vertical template. The goal is to let templates share one provider-neutral entitlement writer without importing a product's plan names, preset capabilities, manual upgrade copy, or payment provider assumptions.

Shared Contract

The shared package should own pure schemas and validators for:

entitlement decision inputs and outputs
plan-source write envelopes
billing lifecycle event normalization
audited write metadata
downgrade and cancellation semantics
public-safe ops summaries

Core may define decision outcomes, writer idempotency, source priority, audit fields, and lifecycle event names. Core should not define the product plan catalog, feature names, quota amounts, upgrade route copy, or final commercial policy.

Core Inputs

Core can receive structured inputs such as:

redacted workspace references
plan-source records after product identity mapping
provider-neutral billing lifecycle events
operator approval references
source priority rules
audit summaries that contain no raw billing provider identifiers

Every input must be safe for an ops summary or release packet. Raw user ids, customer ids, subscription ids, portal URLs, provider webhook payloads, and secret values must stay out of the shared artifact.

Product Adapters

The product template keeps adapters for:

mapping product plan names into capability snapshots
mapping product workspace identity into redacted shared references
mapping Stripe, Paddle, Lemon Squeezy, manual ops, or future providers into the shared lifecycle envelope
applying product-specific upgrade copy and pricing presentation
deciding feature capability names and quota units

Adapters emit audited, provider-neutral writes into the shared contract. Core validates the envelope and can format ops summaries; it does not sell plans or talk to payment providers.

Privacy Rules

The shared validators must reject artifacts containing:

API tokens, bearer tokens, webhook secrets, or provider credentials
raw actor, user, account, workspace, customer, subscription, or owner ids
billing portal URLs or raw webhook payloads
R2 object keys, provider input keys, generated output keys, or private URLs
raw provider execution ids or Gateway metadata

Artifacts may include public plan labels, redacted workspace references, decision outcomes, source kinds, aggregate counts, current commit SHAs, and operator-owned approval reference labels.

Acceptance Fixture

The product-free fixture lives at entitlement-plan-source.core-fixture.json. Before extraction, the fixture must keep these constraints true:

it references entitlement-plan-source
it names cloudflare-saas-core/packages/entitlements as the target
it includes entitlement decision, writer, billing lifecycle, and audit stages
it keeps product adapters separate from core validators
it contains no vertical product name, raw billing id, token marker, or actor identifier

Extraction Sequence

Keep current product-local entitlement decisions and plan-source writes as the source of truth.
Add a second product or billing-provider fixture that maps different plan names into the same writer envelope.
Move only decision envelope validation, lifecycle normalization, idempotency checks, audit summary formatting, and privacy scanning into core.
Keep plan catalogs, feature capabilities, pricing copy, provider SDK calls, and route composition in each product template.
Run the product template's entitlement, billing lifecycle, ops, and staging canary tests before claiming the extraction complete.

Non-Goals

No self-serve checkout.
No billing portal ownership.
No shared plan catalog.
No product pricing decisions.
No provider webhook signature verification unless a separate billing adapter extraction is approved.

On this page