member-console/docs/models/entitlements.md

title, audience, summary

title	audience	summary
Entitlements	developer	How capabilities are defined, delivered, and enforced: sets and their rules, grants as decrees, provisions as delivery, and the materializer that turns it all into effective limits.

Entitlements

Purpose

This model answers "what can this organization actually do, and how much of it?". A capability is named by a resource key (for example fedwiki_sites), carrying a kind — numeric (a countable limit) or boolean (an on/off capability). Most keys are owned by a provider — the registry entity representing an integrated external service such as FedWiki (federated wiki hosting) or Discourse (forums) — which is also the code that enforces them; a key with no provider is platform-owned. An entitlement set bundles rules; a boolean or limit rule says what one resource key grants (the reserved credit rule type names no key). Products point at sets — the Product Catalog card owns that linkage.

Delivery is a five-step pipeline:

1. A funding source exists: a subscription, or a grant — the decree ledger, a durable record that an operator or the system decided to give an organization a product.
2. Conferral turns the source into a provision row in the organization's resource pool, the per-organization container; every organization gets a default pool.
3. Materialization recomputes the pool's effective entitlements from all its live provisions.
4. The results land in two read models: numeric entitlements (core.numeric_entitlements, one limit per resource key, explained row-by-row in core.numeric_entitlement_contributions) and boolean entitlements (core.boolean_entitlements).
5. Consumers read only those materialized rows — never the rules. A consumer resolves its workspace (the working surface an organization gets, where sites and services live; the identity model owns it) to a pool through core.pool_assignments, then reads the pool's rows, and reports consumption into core.numeric_entitlement_usage.

Three statuses live on three different objects and must never be conflated: a grant's status (active/revoked/expired) is issuance history; a provision's status (active/suspended/ended) is the currently-delivering fact; and the "live / superseded / inactive" labels the operator UI shows are derived at read time by joining the two — never stored.

Vocabulary reused from the Product Catalog card: product, conferral, provision, the five conferral functions. From Plan Ladders and Transitions: occupancy, supersession, default restoration. From Payments and Billing: subscription, reconciler.

Where this lives

Database objects sit in the core schema; baseline DDL in internal/db/migrations/00001_init.sql, altered by 00004–00008 (the "doc41" in some file names is an internal change label, nothing more).

Piece	What it is	Where
core.resource_keys	The capability namespace: kind (boolean or numeric) discriminates what rule shape a key accepts; provider names the owning integration, or is empty for platform-owned keys (integrations stamp their ownership at boot)	00001_init.sql; seeds in 00002; kind in 00008_resource_key_kinds.sql
core.entitlement_sets	Named rule bundles; name is unique; a nullable unique key is the row's declarative address for seeds, configuration, tests, scripts, and API clients (NULL unless one of them named the row); is_active gates only whether new products can pick the set	00001_init.sql; 00012_entity_keys.sql
core.entitlement_set_rules	One rule per row: rule_type (boolean/limit/quota/credit), value, stacking policy, per-unit flag — with a CHECK forcing each type's fields into shape; since September 2026 also tier_reduction_policy, the rule's promise about headroom when its limit drops below usage (see Reduction policy)	00001_init.sql; 00018_entitlement_set_changes.sql
core.resource_keys.over_limit_behavior, over_limit_consequence	The provider's declaration of what it does with a surplus (deny_new, park, reclaim) and the one sentence the preview shows for it; stamped by the integration at boot, never operator-edited, platform-owned keys CHECKed to deny_new	00018_entitlement_set_changes.sql
core.entitlement_set_changes, _change_effects, _change_obligations	The rule-change ledger: one append-only act row per rule change with the rule snapshotted before and after, one effect row per pool and key that moved (carrying the changed rule's reduction policy and, since migration 19, the policy governing the pool and key), and the mutable obligations a commit above the synchronous cap leaves for the drain	00018_entitlement_set_changes.sql, 00019_effect_governing_policy.sql
core.commit_rule_change	The sole writer of rule changes: files the act, rewrites the rule, recomputes the carrying pools up to the cap, and leaves obligations for the rest	00018_entitlement_set_changes.sql
core.grants	The decree ledger: who granted which product to whom and why, with extends_grant_id chaining a replacement grant to its ancestor	00001_init.sql; reshaped in 00004
core.pool_provisions	The delivery ledger: one row per (pool, product, source) with quantity, time bounds, and the active/suspended/ended status that is the currently-delivering fact	00001_init.sql; 00004
core.resource_pools, core.pool_assignments	The per-organization container entitlements materialize onto, and its links to workspaces	00001_init.sql
core.numeric_entitlements, core.numeric_entitlement_contributions, core.numeric_entitlement_usage	The materialized numeric limits, the per-provision contribution ledger explaining each limit, and the usage counters consumers increment	00001_init.sql
core.boolean_entitlements	Materialized on/off capabilities: granted true while at least one active provision carries the rule; rows lapse to false but are never deleted, so an absent row always means never-conferred	00007_boolean_entitlements.sql
The five conferral functions	The sole writers of the provision tables (verbs glossed in the ladders card), raising named error codes the conferral boundary translates	00005_doc41_conferral_functions.sql
Grant-lineage guards	A CHECK rejects self-extension; two triggers reject cross-organization lineage and freeze extends_grant_id after insert	00001_init.sql
Materializer	MaterializePoolEntitlements: full in-transaction re-evaluation of a pool's active provisions into limits, contributions, and boolean grants	internal/entitlements/materialize.go
Conferral boundary	Typed wrappers over the five functions, error mapping, and ConferGrantTx — decree, confer, materialize in one transaction	internal/entitlements/conferral.go
Default restoration	Mints and confers the baseline default grant (see the ladders card for the floor guard)	internal/entitlements/reapply_defaults.go
Delivery-state query	ListGrantsWithDelivery derives each grant's live/superseded/inactive label (plus supersession lineage — extends_grant_id and, for a superseded row, the grant that replaced it) by joining onto provisions at read time; one shared query an optional org filter narrows, so the grants index and the per-organization grants table render from the exact same derivation and can never disagree	internal/entitlements/queries/grants.sql
Rule authoring	Operator set and rule CRUD: rule_type derived from the key's kind, stacking fixed to additive (the selector left the form), constraint violations mapped to field errors	internal/server/operator_entitlement_sets.go
Grant issuance	The operator grant forms (quantity capped at 1..1,000,000): issuing composes through ConferGrantTx; extending hand-rolls the same three steps in its own transaction. The Issue Grant form discloses that recording the grant is immediate while any provider-side follow-through it triggers is separately queued work	internal/server/operator_enrollment.go
Grant surfaces	The grants index (/operator/grants) and the per-organization composite both render ListGrantsWithDelivery's rows: delivery state as a badge (never grants.status under a bare "Status" header), lineage, and an in-place ledger-vs-delivery explanation	internal/server/operator_partials.go (index); internal/server/operator_enrollment.go (org detail)
Consumers	The gate for claiming DNS domains (Domains Registry card), the member entitlements panel, and the FedWiki site-limit check reading limit vs usage	internal/server/external_claim_gate.go; internal/server/member_products.go; internal/integrations/fedwiki/web/api.go

Invariants

An invariant is a rule the model guarantees everywhere; code that would break one is wrong even if it works locally. Tags: [db] — a schema constraint rejects violations; [db-code] — database-side code upholds it; [app] — only Go code upholds it. (The position-table invariants live in the ladders card: only the five functions write them (its invariant 2), one live provision per source (4), supersession is whole-bundle and atomic (7). They hold here unchanged.)

1. [db] A set carries at most one active rule per resource key — a partial unique index (a uniqueness rule applied only to rows matching a condition, here active rules with a key) rejects the duplicate at insert — and each rule's fields must match its type: a boolean rule must leave value, stacking, and per-unit empty.
2. [db] A resource key's kind is one of boolean or numeric, CHECK-enforced.
3. [app] Rule shape follows key kind: the authoring form derives the rule type from the chosen key's kind, so the UI cannot create a mismatched rule. No CHECK ties rule_type to the key's kind, so direct SQL still could — the guarantee is app-layer.
4. [db] Every grant names a real product — product_id is NOT NULL, and no column lets a grant point at an entitlement set directly.
5. [db] A grant's reason is one of exactly eight allowed values — manual, default, evaluation, promotional, complimentary, sponsored, board_decision, legacy — and default is legal only on system-authored grants (no granting person recorded).
6. [db-code] Grant lineage is safe: a CHECK rejects self-extension, and triggers reject cross-organization lineage and freeze the lineage pointer after insert.
7. [app] grants.status is issuance history only — active, revoked, expired, written by the operator and expiry paths, with no schema CHECK. The currently-delivering fact lives on the provision's status, and any UI classification is derived per read by joining the two. Code must never read a grant's status as delivery.
8. [app] Materialization is an idempotent full re-evaluation, and it runs in the same database transaction as every conferral-changing write — grant issuance, Stripe reconciliation, expiry, tier changes, default restoration — so effective entitlements never lag a committed conferral.
9. [app] Rule authoring accepts only the additive stacking policy; the policy selector no longer exists on the form, and a request carrying any other value is rejected. The materializer still computes additive and maximum for rows that already carry them, and any other stored value contributes nothing to the limit. (What stacking policies are for, and how mixtures should combine, is an open exploration in status/issues.md.)
10. [app] A boolean entitlement is granted while at least one active provision carries its rule; when the last one goes, the row flips to not-granted but is never deleted — absence always means never-conferred.
11. [app] A per-unit rule contributes its value multiplied by the provision's quantity; a flat rule contributes its value once. The choice is per rule, applied within one provision — quantity never multiplies across provisions.
12. [db] A provision's quantity is positive — a CHECK rejects zero and negatives.
13. [app] The usage counter has one mutator: consumers increment it. The materializer seeds each counter row at zero when it first materializes a limit, then never touches the value; enforcement compares limit to usage at read time.
14. [db] Every rule carries a reduction policy, NOT NULL and CHECK-constrained to block, defer, clamp or force_reduce, defaulting to defer. It is meaningful for limit rules and inert for boolean ones.
15. [db-code] Rule changes reach existing pools: core.commit_rule_change is the only path that writes a rule, and it recomputes every pool carrying the set, synchronously up to the cap and through obligations beyond it, filing one act row and its effects as it goes.

Dimensions

Four quantity-flavored axes come first, because conflating any two of them is this model's classic bug:

• Quantity — how many units one source delivers, stored on the provision; resizing mutates the same row. (Today every checkout confers quantity 1, so the plumbing is exercised only by grants.)
• Provision count — how many sources deliver to the pool; each subscription, purchase, or grant is its own provision, and cross-source accumulation is intentional.
• Per-unit — whether one rule's value multiplies by quantity (within a single provision only).
• Stacking — how contributions from different provisions fold into one limit: additive sums, maximum keeps the largest. Each contribution applies its own rule's policy against the running total, so mixing policies on one resource key gives order-dependent results — a known trap, tracked as a bug candidate in status/issues.md under the entitlements ledger.

And the rest:

• Ledger vs delivery vs position — grants (decree history), provisions (what delivers now), occupancy (which ladder rungs — the ladders card). Three layers; UI must join, never shortcut.
• Rule shape — the key's kind decides boolean vs numeric, which decides the materialized table consumers read.
• Admitted vs materialized rule types — the schema's CHECK admits four types, but only boolean and limit materialize; quota and credit are reserved (their intended machinery — periodic reset, spendable balance — is unbuilt), the UI never offers them, and the materializer skips any that direct SQL might create.
• Definition vs usage — limits say what is allowed; usage counters say what is consumed; the comparison happens at the consumer (invariant 13).
• Conferral snapshot vs current catalog — a provision freezes its product and set at conferral; when the catalog changes shape under a live provision, core.align_conferral_shape reconciles its ladder occupancy — the frozen product and set on the provision itself are never rewritten.
• Reduction policy vs over-limit behavior — the rule says whether a surplus is acted on (the promise to the member); the resource key says what its provider does with one (park, reclaim, or refuse new). The policy decides whether the behavior is exercised. See the next section.

Reduction policy

A limit can drop below what a pool already uses: a rule is lowered or removed, a plan is downgraded, a grant expires. The rule's tier_reduction_policy is the platform's promise to the member about that moment (Decision 125 in the model; Decisions 143 and 147 brought it into this codebase in September 2026). Four values exist. The designed meaning is the model's; the as-built column is what this codebase does today.

Value	Designed meaning (data model, Decision 125)	As built today	Strength
force_reduce	Apply the new limit immediately, even below current usage; the provider acts on the surplus	Exercised. The FedWiki quota sweep parks the excess sites read-only when the governing policy is force_reduce (internal/integrations/fedwiki/workflows/reconcile.go); the preview names the provider's over_limit_consequence sentence	1, strongest
clamp	Lower the ceiling but keep existing usage above it until it drains; refuse increments meanwhile	Exercised, and needs no wiring: AtomicIncrementUsage refuses while current_usage >= resource_limit; nothing is parked	2
block	Disallow the reducing change, as a precondition on the switch request	Not wired. Behaves as clamp: a rule commit has "no boundary" and the preview says so	3
defer (default)	Grandfather the prior allocation until the period or term boundary, via a scheduled change	Not wired. Behaves as clamp at a rule commit and on downgrades; the console has done so since v14	4, weakest

Strength and the fold. A pool's key can be funded by rules from more than one set (two products held at once, a plan plus a grant). The policy that governs the pool is the strongest of the funding rules' policies, in the order of the Strength column: force_reduce, then clamp, then block, then defer. The order is stated once as a list in the Go fold (governingPolicy in internal/entitlements/materialize.go, which reports it per key beside the resolved value) and once as an explicit ordered CASE in GetGoverningReductionPolicy (internal/entitlements/queries/entitlement_set_rules.sql); a test feeds both the same mixtures. The reasoning: a promise the member's provider will act on cannot be weakened by a second product the member also holds. Chosen by the maintainer on 2026-09-18 over the alternative (the primary provision's rule governs), recorded in status/issues.md under "Reduction policies from several sets on one pool", and stated as a requirement by the staged-rule-changes change (entitlements, "The reduction policy governing a pool and key is the strongest across the rules funding it").

Who reads what. The FedWiki sweep reads the governing policy through the query. A rule commit reads it from the fold and stamps it on every effect row beside the changed rule's own policy (governing_policy, migration 19), so a reader sees when a rule's own policy was not the one that governed. The operator's rule-change surface offers a rule's own policy for editing and discloses nothing per pool; the batch dry run (RuleChangeBatchPreview) carries the governing policy for the review-details link that a later change adds.

Drift to carry upstream. The model defines four values and where each is enforced; it does not define how policies from several sets combine. Under the documentation division (Decisions 140 and 141) that is a Stage-1 issue for membcons-db, filed now that the console's spec states the fold; this card describes, it does not settle.