member-console/docs/models/entitlements.md

---
title: "Entitlements"
audience: [developer]
summary: "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-catalog.md): product, conferral, provision, the five conferral functions. From [Plan Ladders and Transitions](plan-ladders-transitions.md): occupancy, supersession, default restoration. From [Payments and Billing](payments-billing.md): 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; `is_active` gates only whether new products can pick the set | `00001_init.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 | `00001_init.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](domains-registry.md)), 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.

## 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.