feat(license): metered licensing — catalogue, entitlements, and enforcement

Implements spec 7 tasks 2-10 on top of the six-plan payload from task 1.

Admin: plans re-keyed on (deployment, tier); new catalogue collection holds
every Paddle price ID (one row per priceable component); new entitlements
collection holds desired beside granted. admin/internal/catalogue owns both
folds — entitlement to licence limits, and entitlement to Paddle line items —
so the base allowance is subtracted in exactly one place. licensing.Issue now
snapshots the instance's granted entitlement, never desired. Free is enforced
per account AND deployment. Staff endpoints for plans, catalogue and
entitlements; Free self-hosted can be claimed and renewed on its annual term;
the reaper stays cloud-only.

Server: enforces the monitor cap, audit-log retention (daily sweep, skips
Unlimited and lapsed instances), and gates the OIDC callback. Unset limits are
filled from the seed plan at the single decode site so old blobs never read as
zero.

Frontends: adminsite gains a catalogue price-ID editor, six-plan allowance
screen, and a catalogue-driven PlanConfigurator mounted on the staff instance
page. web shows monitors, audit retention and support level on the licence page.

Docs: CLAUDE.md, spec index and plan 5 preamble updated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

admin/internal/api/customer.go

@@ -221,8 +221,13 @@ func createInstance(c *gin.Context) {
 
 	// Pre-check the Free rule so we never create an instance we then cannot
 	// licence. licensing.Issue enforces it too; this is the friendly refusal.
+	//
+	// Scoped to cloud because that is what this endpoint creates. It MUST match
+	// checkFreeLimit's scoping — a pre-check stricter than the issuer refuses
+	// something that would have worked.
 	n, err := db.Admin("admin_instances").CountDocuments(ctx, bson.M{
 		"account_id": s.AccountID,
+		"deployment": license.DeploymentCloud,
 		"tier":       license.TierFree,
 		"status":     bson.M{"$ne": models.StatusCancelled},
 	})
@@ -232,7 +237,7 @@ func createInstance(c *gin.Context) {
 	}
 	if n > 0 {
 		c.JSON(http.StatusConflict, gin.H{
-			"error": "this account already has a Free instance"})
+			"error": "this account already has a Free cloud instance"})
 		return
 	}
 
@@ -364,10 +369,16 @@ func renewInstance(c *gin.Context) {
 		return
 	}
 
+	// Free renews on its deployment's only term: monthly for cloud, annual for
+	// self-hosted. Reading it from TermsFor rather than hardcoding is what stops
+	// a self-hosted instance being handed a one-month licence.
+	terms := license.TermsFor(inst.Deployment)
+	term := terms[len(terms)-1]
+
 	lic, err := licensing.Issue(ctx, licensing.IssueInput{
 		InstanceID: inst.InstanceID,
 		Tier:       license.TierFree,
-		Term:       "monthly",
+		Term:       term,
 		Reason:     models.ReasonRenewal,
 		IssuedBy:   "self-serve",
 	})
@@ -375,7 +386,9 @@ func renewInstance(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	inject.Deliver(ctx, lic)
+	// Cloud is injected; self-hosted is delivered to the customer, because their
+	// database is theirs and we cannot write to it.
+	deliver(c, inst, lic)
 
 	// Clear the notice log so the next term starts the sequence again. Issue has
 	// already set status back to active.
@@ -414,6 +427,90 @@ var appLoginURL string
 // SetAppLoginURL is called from main.
 func SetAppLoginURL(v string) { appLoginURL = v }
 
+// claimFree issues a Free licence on a linked self-hosted instance.
+//
+// The link step creates the row; this gives it a licence. They are separate
+// because linking is about identity — proving which install is yours — and
+// claiming is about entitlement, and a customer who links an install and then
+// changes their mind should not have consumed their one Free allowance.
+//
+// Free is outside Paddle entirely, so there is no checkout, no subscription and
+// nothing to reconcile. licensing.Issue's own checkFreeLimit is the real guard;
+// the count here exists to refuse politely before anything is written.
+func claimFree(c *gin.Context) {
+	inst, ok := ownedInstance(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	ctx := c.Request.Context()
+
+	// Cloud Free is claimed at creation by POST /api/instances. Allowing it here
+	// too would be a second way to reach the same state, with its own bugs.
+	if inst.Deployment != license.DeploymentSelfHosted {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": "cloud instances get their Free licence when they are created"})
+		return
+	}
+	if inst.CurrentLicense != "" {
+		c.JSON(http.StatusConflict, gin.H{
+			"error": "this instance already has a licence"})
+		return
+	}
+
+	plan, err := models.GetPlan(ctx, license.DeploymentSelfHosted, license.TierFree)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "no Free plan configured"})
+		return
+	}
+	if !plan.Active {
+		c.JSON(http.StatusForbidden, gin.H{
+			"error": "Free self-hosted is not currently offered"})
+		return
+	}
+
+	// The entitlement is written BEFORE the licence, so Issue snapshots it rather
+	// than falling back to the plan base. They are the same numbers today, but
+	// the ordering is what makes that a coincidence rather than a dependency.
+	if err := models.UpsertEntitlement(ctx, models.Entitlement{
+		InstanceID:     inst.InstanceID,
+		AccountID:      inst.AccountID,
+		Deployment:     license.DeploymentSelfHosted,
+		Tier:           license.TierFree,
+		Term:           "annual",
+		Desired:        models.Config{Servers: plan.BaseLimits.MaxServers, Features: models.Features{}},
+		Granted:        models.Config{Servers: plan.BaseLimits.MaxServers, Features: models.Features{}},
+		ResolvedLimits: plan.BaseLimits,
+	}); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	s := auth.Current(c)
+	lic, err := licensing.Issue(ctx, licensing.IssueInput{
+		InstanceID: inst.InstanceID,
+		Tier:       license.TierFree,
+		// Annual, and not a choice. Self-hosted sells annual only because the
+		// term length is the revocation window for an offline licence.
+		Term:     "annual",
+		Reason:   models.ReasonNew,
+		IssuedBy: s.Email,
+	})
+	if err != nil {
+		status := http.StatusBadRequest
+		if errors.Is(err, licensing.ErrFreeLimit) {
+			status = http.StatusConflict
+		}
+		c.JSON(status, gin.H{"error": err.Error()})
+		return
+	}
+
+	deliver(c, inst, lic)
+	audit.Write(ctx, models.AuditEntry{
+		Actor: s.Email, Action: "instance.claimed_free", AccountID: s.AccountID,
+		Target: inst.InstanceID, Detail: "self-hosted Free, annual", IP: c.ClientIP()})
+	c.JSON(http.StatusCreated, lic)
+}
+
 // deliver sends a freshly issued licence where it needs to go. Cloud instances
 // are injected; self-hosted customers are emailed and can download.
 //

admin/internal/api/entitlement.go

@@ -0,0 +1,187 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/auth"
+	"github.com/mrhid6/vantage/admin/internal/catalogue"
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// entitlementBody is what a caller may set.
+//
+// Only Desired is writable. Granted is what a payment confirmed, and letting a
+// form set it would let the portal grant itself a licence — which is the one
+// thing this whole split exists to prevent. Staff promote Granted explicitly
+// through a separate flag, because staff issuing a licence to somebody who has
+// not paid is a real operation with a real reason, and it should be one they
+// took on purpose and left an audit row for.
+type entitlementBody struct {
+	Tier     string   `json:"tier"`
+	Term     string   `json:"term"`
+	Servers  int      `json:"servers"`
+	Features []string `json:"features"`
+	// Grant promotes Desired into Granted in the same write. Staff only.
+	Grant bool `json:"grant"`
+}
+
+// getEntitlement serves the customer's own view of one instance's configuration.
+func getEntitlement(c *gin.Context) {
+	inst, ok := ownedInstance(c, c.Param("id"))
+	if !ok {
+		return
+	}
+	ent, err := models.GetEntitlement(c.Request.Context(), inst.InstanceID)
+	if errors.Is(err, models.ErrNoEntitlement) {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no entitlement"})
+		return
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"entitlement": ent, "pending": ent.Pending()})
+}
+
+func staffGetEntitlement(c *gin.Context) {
+	var inst models.Instance
+	if err := db.Admin("admin_instances").FindOne(c.Request.Context(),
+		bson.M{"instance_id": c.Param("id")}).Decode(&inst); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no such instance"})
+		return
+	}
+	ent, err := models.GetEntitlement(c.Request.Context(), inst.InstanceID)
+	if errors.Is(err, models.ErrNoEntitlement) {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no entitlement"})
+		return
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"entitlement": ent, "pending": ent.Pending()})
+}
+
+// staffSetEntitlement writes an instance's configuration.
+//
+// This is the endpoint that makes metering usable before Paddle exists: staff
+// configure, then issue. It does NOT issue — recording what an instance is
+// allowed and signing a licence for it stay separate, so a bad configuration is
+// a row to correct rather than a licence to supersede.
+func staffSetEntitlement(c *gin.Context) {
+	ctx := c.Request.Context()
+	var body entitlementBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid entitlement"})
+		return
+	}
+
+	var inst models.Instance
+	if err := db.Admin("admin_instances").FindOne(ctx,
+		bson.M{"instance_id": c.Param("id")}).Decode(&inst); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no such instance"})
+		return
+	}
+
+	tier := body.Tier
+	if tier == "" {
+		tier = inst.Tier
+	}
+	plan, err := models.GetPlan(ctx, inst.Deployment, tier)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": fmt.Sprintf("no plan for %s/%s", inst.Deployment, tier)})
+		return
+	}
+	if !termSold(inst.Deployment, body.Term) {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": fmt.Sprintf("%s does not sell %s", inst.Deployment, body.Term)})
+		return
+	}
+	if body.Servers < plan.BaseLimits.MaxServers &&
+		plan.BaseLimits.MaxServers != -1 {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error": fmt.Sprintf("%s includes %d servers; cannot configure fewer",
+				plan.Name, plan.BaseLimits.MaxServers)})
+		return
+	}
+
+	desired := models.Config{
+		Servers:  body.Servers,
+		Features: models.Features(body.Features).OrEmpty(),
+	}
+
+	// Start from whatever is already granted, so writing a desired change never
+	// silently alters what the instance is currently allowed.
+	granted := desired
+	existing, err := models.GetEntitlement(ctx, inst.InstanceID)
+	switch {
+	case err == nil:
+		if !body.Grant {
+			granted = existing.Granted
+		}
+	case errors.Is(err, models.ErrNoEntitlement):
+		// First write. There is nothing granted to preserve, so desired becomes
+		// granted — an instance with an entitlement nobody has granted would
+		// fall back to the plan base at issue time and confuse everyone.
+	default:
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// Only the limits are stored. Features are NOT snapshotted onto the
+	// entitlement: they live in Granted.Features, and Issue resolves them again
+	// against the catalogue at signing time. Storing a second copy here would
+	// give two answers to "which features does this instance have".
+	limits, _, err := catalogue.Resolve(ctx, plan, granted)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	ent := models.Entitlement{
+		InstanceID:     inst.InstanceID,
+		AccountID:      inst.AccountID,
+		Deployment:     inst.Deployment,
+		Tier:           tier,
+		Term:           body.Term,
+		Desired:        desired,
+		Granted:        granted,
+		ResolvedLimits: limits,
+	}
+	// A reduction is a fact about the future, so it carries a date. There is no
+	// billing period to read yet — plan 5 sets this from the subscription — so
+	// staff-set reductions are marked as pending without one.
+	if desired.Servers < granted.Servers {
+		now := time.Now().UTC()
+		ent.ScheduledChangeAt = &now
+	}
+	if existing != nil {
+		ent.GrantedAt = existing.GrantedAt
+	}
+	if body.Grant {
+		ent.GrantedAt = time.Now().UTC()
+	}
+
+	if err := models.UpsertEntitlement(ctx, ent); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	audit.Write(ctx, models.AuditEntry{
+		Actor:     auth.Current(c).Email,
+		Action:    "entitlement.updated",
+		AccountID: inst.AccountID,
+		Target:    inst.InstanceID,
+		Detail: fmt.Sprintf("tier=%s term=%s desired_servers=%d granted_servers=%d granted=%t",
+			tier, body.Term, desired.Servers, granted.Servers, body.Grant),
+	})
+	c.JSON(http.StatusOK, gin.H{"entitlement": ent, "pending": ent.Pending()})
+}

admin/internal/api/routes.go

@@ -68,6 +68,10 @@ func Routes(cfg config.Config) http.Handler {
 		cust.POST("/instances/link", linkInstance)
 		cust.POST("/instances/:id/relink", relinkInstance)
 		cust.POST("/instances/:id/renew", renewInstance)
+		cust.POST("/instances/:id/claim-free",
+			auth.RequireAccountRole(models.AccountRoleOwner, models.AccountRoleAdmin),
+			claimFree)
+		cust.GET("/instances/:id/entitlement", getEntitlement)
 		cust.GET("/instances/:id/license", getInstanceLicense)
 		cust.GET("/instances/:id/license/download", downloadInstanceLicense)
 		cust.GET("/instances/:id/members", listInstanceMembers)
@@ -98,7 +102,15 @@ func Routes(cfg config.Config) http.Handler {
 		staff.POST("/instances/:id/relink", staffRelink)
 		staff.GET("/licenses", staffListLicenses)
 		staff.GET("/plans", staffListPlans)
-		staff.PUT("/plans/:tier", staffUpdatePlan)
+		// Plans are keyed on the pair now, so the path is too. A single :tier
+		// segment could name three rows.
+		staff.PUT("/plans/:deployment/:tier", staffUpdatePlan)
+
+		staff.GET("/catalogue", staffListCatalogue)
+		staff.PUT("/catalogue", staffUpdateCatalogue)
+
+		staff.GET("/instances/:id/entitlement", staffGetEntitlement)
+		staff.PUT("/instances/:id/entitlement", staffSetEntitlement)
 		staff.GET("/audit", staffAudit)
 		staff.GET("/health/injection", staffInjectionHealth)
 	}

admin/internal/api/staff.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	"fmt"
 	"net/http"
 	"strings"
 	"time"
@@ -393,31 +394,130 @@ func staffListPlans(c *gin.Context) {
 	c.JSON(http.StatusOK, plans)
 }
 
-// staffUpdatePlan changes what a tier grants FROM NOW ON. Existing licences
-// snapshotted their plan at issue time and are unaffected — the same rule as
-// workflow_runs.steps_snapshot.
+// staffUpdatePlan changes what a (deployment, tier) pair grants FROM NOW ON.
+// Existing licences snapshotted their plan at issue time and are unaffected —
+// the same rule as workflow_runs.steps_snapshot.
+//
+// It writes no Paddle identifiers: those live in the catalogue, because a
+// metered plan is priced by several components.
 func staffUpdatePlan(c *gin.Context) {
 	var body models.Plan
 	if err := c.ShouldBindJSON(&body); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid plan"})
 		return
 	}
+	deployment, tier := c.Param("deployment"), c.Param("tier")
 	set := bson.M{
-		"name":              body.Name,
-		"limits":            body.Limits,
-		"features":          body.Features.OrEmpty(),
-		"paddle_product_id": body.PaddleProductID,
-		"paddle_price_ids":  body.PaddlePriceIDs,
-		"active":            body.Active,
+		"name":          body.Name,
+		"base_limits":   body.BaseLimits,
+		"base_features": body.BaseFeatures.OrEmpty(),
+		"support_level": body.SupportLevel,
+		"active":        body.Active,
 	}
-	if _, err := db.Admin("plans").UpdateOne(c.Request.Context(),
-		bson.M{"tier": c.Param("tier")}, bson.M{"$set": set}); err != nil {
+	res, err := db.Admin("plans").UpdateOne(c.Request.Context(),
+		bson.M{"deployment": deployment, "tier": tier}, bson.M{"$set": set})
+	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
+	if res.MatchedCount == 0 {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no such plan"})
+		return
+	}
+	audit.Write(c.Request.Context(), models.AuditEntry{
+		Actor:  auth.Current(c).Email,
+		Action: "plan.updated",
+		Target: deployment + "/" + tier,
+		Detail: fmt.Sprintf("servers=%d monitors=%d support=%s active=%t",
+			body.BaseLimits.MaxServers, body.BaseLimits.MaxMonitors,
+			body.SupportLevel, body.Active),
+	})
 	c.JSON(http.StatusOK, gin.H{"updated": true})
 }
 
+func staffListCatalogue(c *gin.Context) {
+	rows, err := models.AllCatalogue(c.Request.Context())
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, rows)
+}
+
+// staffUpdateCatalogue sets the price IDs on one component.
+//
+// The component is addressed by its natural key rather than by an ObjectID, so
+// the staff UI never has to hold a Mongo identifier and a seeded row can be
+// updated the moment it exists. Only price IDs are writable: a row's kind, plan
+// and key are seeded by SeedCatalogue, and letting a form invent a limit_key
+// would let it invent a limit nothing enforces.
+func staffUpdateCatalogue(c *gin.Context) {
+	var body struct {
+		Kind       string                       `json:"kind"`
+		Deployment string                       `json:"deployment"`
+		Tier       string                       `json:"tier"`
+		LimitKey   string                       `json:"limit_key"`
+		FeatureKey string                       `json:"feature_key"`
+		PriceIDs   map[string]map[string]string `json:"price_ids"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid component"})
+		return
+	}
+
+	// Refuse a price on a term the deployment does not sell. Storing one would
+	// mean a resolved self-hosted monthly price later, which the resolver treats
+	// as a configuration error — better to refuse it at the point somebody
+	// pastes it, while they are looking at the screen.
+	for env, byTerm := range body.PriceIDs {
+		for term, id := range byTerm {
+			if id == "" {
+				continue
+			}
+			if !termSold(body.Deployment, term) {
+				c.JSON(http.StatusBadRequest, gin.H{
+					"error": fmt.Sprintf("%s does not sell %s (environment %s)",
+						body.Deployment, term, env)})
+				return
+			}
+		}
+	}
+
+	filter := bson.M{
+		"kind":        body.Kind,
+		"deployment":  body.Deployment,
+		"tier":        body.Tier,
+		"limit_key":   body.LimitKey,
+		"feature_key": body.FeatureKey,
+	}
+	res, err := db.Admin("catalogue").UpdateOne(c.Request.Context(), filter,
+		bson.M{"$set": bson.M{"price_ids": body.PriceIDs}})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if res.MatchedCount == 0 {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no such component"})
+		return
+	}
+	audit.Write(c.Request.Context(), models.AuditEntry{
+		Actor:  auth.Current(c).Email,
+		Action: "catalogue.updated",
+		Target: body.Deployment + "/" + body.Tier + "/" + body.Kind,
+		Detail: body.LimitKey + body.FeatureKey,
+	})
+	c.JSON(http.StatusOK, gin.H{"updated": true})
+}
+
+func termSold(deployment, term string) bool {
+	for _, t := range license.TermsFor(deployment) {
+		if t == term {
+			return true
+		}
+	}
+	return false
+}
+
 func staffAudit(c *gin.Context) {
 	filter := bson.M{}
 	if v := c.Query("account_id"); v != "" {

admin/internal/catalogue/catalogue.go

@@ -0,0 +1,120 @@
+// Package catalogue turns an entitlement into the two things derived from it:
+// the limits and features a licence grants, and the Paddle line items a
+// subscription is made of.
+//
+// Both folds live here so the arithmetic exists once. The temptation is to
+// compute limits in the issuer and quantities in the checkout, and then the two
+// disagree about whether the base allowance is included in the number — which is
+// a bug that bills a customer for three servers they were given.
+package catalogue
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"github.com/mrhid6/vantage/shared/license"
+)
+
+var (
+	// ErrUnknownPrice means an item named a price ID no catalogue row claims.
+	//
+	// This is always a configuration error and never a customer error: someone
+	// bought something at a price we cannot map to a plan. It must fail loudly
+	// rather than guess a tier — a guessed tier is a wrong licence with no
+	// record of why.
+	ErrUnknownPrice = errors.New("no catalogue row claims that price ID")
+
+	// ErrNoBaseItem means no item matched a base row, so the subscription names
+	// no plan. Quantities are meaningless without one.
+	ErrNoBaseItem = errors.New("no item matches a base price; the subscription names no plan")
+
+	// ErrTermNotSold means a price resolved to a term its deployment does not
+	// sell — in practice a self-hosted monthly price.
+	ErrTermNotSold = errors.New("that deployment does not sell that term")
+
+	// ErrUnpriced means a component needed for this configuration has no price
+	// ID in this environment. Refusing is correct: a checkout that silently
+	// drops a paid line item gives away the thing it was meant to charge for.
+	ErrUnpriced = errors.New("component has no price in this environment")
+)
+
+// Resolve folds a configuration into the limits and features a licence grants.
+//
+// Limits start at the plan's base and each metered component adds its configured
+// amount. Features are the plan's base features plus the configured ones,
+// deduplicated and filtered to keys the catalogue actually offers — a stale
+// feature key in a stored entitlement must not survive into a signed payload.
+func Resolve(ctx context.Context, plan *models.Plan, cfg models.Config) (license.Limits, []string, error) {
+	rows, err := models.CatalogueFor(ctx, plan.Deployment, plan.Tier)
+	if err != nil {
+		return license.Limits{}, nil, err
+	}
+
+	limits := plan.BaseLimits
+	offered := map[string]bool{}
+	for _, r := range rows {
+		switch r.Kind {
+		case models.KindLimit:
+			if err := addLimit(&limits, r.LimitKey, configured(cfg, r.LimitKey), plan.BaseLimits); err != nil {
+				return license.Limits{}, nil, err
+			}
+		case models.KindFeature:
+			offered[r.FeatureKey] = true
+		}
+	}
+
+	seen := map[string]bool{}
+	features := []string{}
+	for _, f := range plan.BaseFeatures {
+		if !seen[f] {
+			seen[f] = true
+			features = append(features, f)
+		}
+	}
+	for _, f := range cfg.Features {
+		if seen[f] || !offered[f] {
+			continue
+		}
+		seen[f] = true
+		features = append(features, f)
+	}
+	return limits, features, nil
+}
+
+// configured reads the configured total for one metered limit key.
+//
+// A switch rather than reflection, so every metered dimension is greppable and
+// adding one is a visible edit here as well as a catalogue row.
+func configured(cfg models.Config, limitKey string) int {
+	switch limitKey {
+	case models.LimitKeyServers:
+		return cfg.Servers
+	default:
+		return 0
+	}
+}
+
+// addLimit sets a metered limit to its configured total.
+//
+// The configured value is a TOTAL, not an increment, so this assigns rather than
+// adds. A base of Unlimited is left alone: nothing can be added to no cap, and a
+// plan that meters an already-unlimited dimension is a configuration mistake
+// rather than something to compute around.
+func addLimit(l *license.Limits, limitKey string, total int, base license.Limits) error {
+	switch limitKey {
+	case models.LimitKeyServers:
+		if base.MaxServers == license.Unlimited {
+			return nil
+		}
+		if total > base.MaxServers {
+			l.MaxServers = total
+		}
+		return nil
+	case "":
+		return fmt.Errorf("catalogue limit row has no limit_key")
+	default:
+		return fmt.Errorf("%w: limit_key %q", ErrUnknownPrice, limitKey)
+	}
+}

admin/internal/catalogue/items.go

@@ -0,0 +1,206 @@
+package catalogue
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/mrhid6/vantage/admin/internal/models"
+	"github.com/mrhid6/vantage/shared/license"
+)
+
+// Item is one Paddle line item: a price and how many of it.
+type Item struct {
+	PriceID  string `json:"price_id"`
+	Quantity int    `json:"quantity"`
+}
+
+// LineItems builds the subscription items for a configuration.
+//
+// The base row is always quantity 1. A metered row's quantity is the configured
+// TOTAL minus the plan's base allowance, so a Professional customer at exactly
+// three servers has a single-item subscription rather than one with a zero
+// quantity Paddle would reject. A feature with no price in this environment
+// produces no item and is granted free.
+func LineItems(ctx context.Context, env, term string, plan *models.Plan, cfg models.Config) ([]Item, error) {
+	if !sells(plan.Deployment, term) {
+		return nil, fmt.Errorf("%w: %s does not sell %s", ErrTermNotSold, plan.Deployment, term)
+	}
+	rows, err := models.CatalogueFor(ctx, plan.Deployment, plan.Tier)
+	if err != nil {
+		return nil, err
+	}
+	if len(rows) == 0 {
+		return nil, fmt.Errorf("%w: %s/%s is priced by nothing",
+			ErrUnpriced, plan.Deployment, plan.Tier)
+	}
+
+	wanted := map[string]bool{}
+	for _, f := range cfg.Features {
+		wanted[f] = true
+	}
+
+	items := []Item{}
+	for _, r := range rows {
+		switch r.Kind {
+		case models.KindBase:
+			id := r.PriceID(env, term)
+			if id == "" {
+				return nil, fmt.Errorf("%w: base price for %s/%s in %s",
+					ErrUnpriced, plan.Deployment, plan.Tier, env)
+			}
+			items = append(items, Item{PriceID: id, Quantity: 1})
+
+		case models.KindLimit:
+			qty := billable(cfg, r.LimitKey, plan.BaseLimits)
+			if qty <= 0 {
+				continue
+			}
+			id := r.PriceID(env, term)
+			if id == "" {
+				return nil, fmt.Errorf("%w: %s price for %s/%s in %s",
+					ErrUnpriced, r.LimitKey, plan.Deployment, plan.Tier, env)
+			}
+			items = append(items, Item{PriceID: id, Quantity: qty})
+
+		case models.KindFeature:
+			if !wanted[r.FeatureKey] {
+				continue
+			}
+			id := r.PriceID(env, term)
+			if id == "" {
+				// Free to toggle. Resolve() still grants it.
+				continue
+			}
+			items = append(items, Item{PriceID: id, Quantity: 1})
+		}
+	}
+	return items, nil
+}
+
+// billable is how many UNITS to charge for a metered dimension.
+//
+// The configured value is the total the customer sees, which includes the base
+// allowance they were given. Charging for that base is the single most likely
+// bug in this file, so the subtraction lives here and nowhere else.
+func billable(cfg models.Config, limitKey string, base license.Limits) int {
+	switch limitKey {
+	case models.LimitKeyServers:
+		if base.MaxServers == license.Unlimited {
+			return 0
+		}
+		return cfg.Servers - base.MaxServers
+	default:
+		return 0
+	}
+}
+
+// Match is what an item list says about itself.
+type Match struct {
+	Deployment string
+	Tier       string
+	Term       string
+	Servers    int
+	Features   []string
+}
+
+// ResolveItems maps a full item list back to a plan and a configuration.
+//
+// This replaces a price-ID-to-tier lookup, which cannot work once a subscription
+// has several prices. The base item identifies the plan and the term; everything
+// else is read relative to it. An item matching nothing fails the whole list.
+//
+// Only the running environment's IDs are consulted, so a production process
+// cannot be talked into resolving a sandbox price by a forged or misrouted
+// event.
+//
+// It is a function of the COMPLETE list, which is what keeps out-of-order
+// delivery correct by construction: Paddle sends every item on every
+// subscription event, so reading all of them is reading current state rather
+// than a transition.
+func ResolveItems(ctx context.Context, env string, items []Item) (Match, error) {
+	all, err := models.AllCatalogue(ctx)
+	if err != nil {
+		return Match{}, err
+	}
+
+	// Pass 1: find the base item. Until we know the plan, no other item means
+	// anything — a quantity of 7 is 7 of what?
+	var m Match
+	found := false
+	for _, it := range items {
+		for _, r := range all {
+			if r.Kind != models.KindBase {
+				continue
+			}
+			for _, term := range []string{"monthly", "annual"} {
+				if r.PriceID(env, term) != it.PriceID || it.PriceID == "" {
+					continue
+				}
+				if found {
+					return Match{}, fmt.Errorf(
+						"item list names two plans: %s/%s and %s/%s",
+						m.Deployment, m.Tier, r.Deployment, r.Tier)
+				}
+				m.Deployment, m.Tier, m.Term = r.Deployment, r.Tier, term
+				found = true
+			}
+		}
+	}
+	if !found {
+		return Match{}, ErrNoBaseItem
+	}
+	if !sells(m.Deployment, m.Term) {
+		return Match{}, fmt.Errorf("%w: price resolves to %s %s; remove it from the catalogue",
+			ErrTermNotSold, m.Deployment, m.Term)
+	}
+
+	plan, err := models.GetPlan(ctx, m.Deployment, m.Tier)
+	if err != nil {
+		return Match{}, fmt.Errorf("item list names plan %s/%s, which does not exist: %w",
+			m.Deployment, m.Tier, err)
+	}
+	m.Servers = plan.BaseLimits.MaxServers
+	m.Features = []string{}
+
+	// Pass 2: everything else, relative to that plan. An item matching no row of
+	// this plan is a configuration error even if it matches some other plan's
+	// row — mixing two plans in one subscription is not a thing we sell.
+	rows, err := models.CatalogueFor(ctx, m.Deployment, m.Tier)
+	if err != nil {
+		return Match{}, err
+	}
+	for _, it := range items {
+		matched := false
+		for _, r := range rows {
+			if r.PriceID(env, m.Term) != it.PriceID {
+				continue
+			}
+			matched = true
+			switch r.Kind {
+			case models.KindBase:
+				// Already handled.
+			case models.KindLimit:
+				if r.LimitKey == models.LimitKeyServers {
+					m.Servers = plan.BaseLimits.MaxServers + it.Quantity
+				}
+			case models.KindFeature:
+				m.Features = append(m.Features, r.FeatureKey)
+			}
+		}
+		if !matched {
+			return Match{}, fmt.Errorf("%w: %s (environment %s, plan %s/%s)",
+				ErrUnknownPrice, it.PriceID, env, m.Deployment, m.Tier)
+		}
+	}
+	return m, nil
+}
+
+// sells reports whether a deployment offers a term.
+func sells(deployment, term string) bool {
+	for _, t := range license.TermsFor(deployment) {
+		if t == term {
+			return true
+		}
+	}
+	return false
+}

admin/internal/db/db.go

@@ -11,6 +11,7 @@ package db
 import (
 	"context"
 	"fmt"
+	"log"
 	"time"
 
 	"github.com/mrhid6/vantage/admin/internal/config"
@@ -84,7 +85,6 @@ func EnsureIndexes(ctx context.Context) error {
 		{"accounts", "account_id"},
 		{"admin_instances", "instance_id"},
 		{"licenses", "license_id"},
-		{"plans", "tier"},
 		{"staff_users", "email"},
 		{"customer_users", "email"},
 	}
@@ -106,6 +106,34 @@ func EnsureIndexes(ctx context.Context) error {
 		return fmt.Errorf("index subscriptions.paddle_subscription_id: %w", err)
 	}
 
+	// plans was unique on tier alone until spec 7. Mongo will not replace an
+	// index implicitly, and the old one would refuse the second row of every
+	// tier, so it is dropped by name here. Dropping a missing index is not an
+	// error worth failing boot over — a fresh database has never had it.
+	if err := Admin("plans").Indexes().DropOne(ctx, "tier_unique"); err != nil {
+		log.Printf("index plans.tier_unique: not dropped (%v); expected on a fresh database", err)
+	}
+
+	for _, u := range []struct {
+		coll string
+		keys bson.D
+		name string
+	}{
+		{"plans", bson.D{{Key: "deployment", Value: 1}, {Key: "tier", Value: 1}}, "deployment_tier_unique"},
+		{"catalogue", bson.D{
+			{Key: "deployment", Value: 1}, {Key: "tier", Value: 1}, {Key: "kind", Value: 1},
+			{Key: "limit_key", Value: 1}, {Key: "feature_key", Value: 1},
+		}, "component_unique"},
+		{"entitlements", bson.D{{Key: "instance_id", Value: 1}}, "instance_id_unique"},
+	} {
+		if _, err := Admin(u.coll).Indexes().CreateOne(ctx, mongo.IndexModel{
+			Keys:    u.keys,
+			Options: options.Index().SetUnique(true).SetName(u.name),
+		}); err != nil {
+			return fmt.Errorf("index %s.%s: %w", u.coll, u.name, err)
+		}
+	}
+
 	for _, idx := range []struct {
 		coll string
 		keys bson.D

admin/internal/licensing/issue.go

@@ -5,10 +5,12 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"log"
 	"time"
 
 	"github.com/google/uuid"
 	"github.com/mrhid6/vantage/admin/internal/audit"
+	"github.com/mrhid6/vantage/admin/internal/catalogue"
 	"github.com/mrhid6/vantage/admin/internal/db"
 	"github.com/mrhid6/vantage/admin/internal/models"
 	"github.com/mrhid6/vantage/shared/license"
@@ -18,7 +20,7 @@ import (
 var (
 	ErrUnknownTier        = errors.New("unknown tier")
 	ErrDeploymentMismatch = errors.New("that plan is not available for this deployment type")
-	ErrFreeLimit          = errors.New("this account already has a Free instance")
+	ErrFreeLimit          = errors.New("this account already has a Free instance of that deployment type")
 	ErrUnknownInstance    = errors.New("instance not found")
 )
 
@@ -54,7 +56,10 @@ func Issue(ctx context.Context, in IssueInput) (*models.License, error) {
 		return nil, ErrUnknownInstance
 	}
 
-	plan, err := models.GetPlan(ctx, in.Tier)
+	// The plan is looked up by the INSTANCE's deployment, not by a caller's
+	// guess. That is what makes the deployment comparison below a consistency
+	// check rather than the thing that decides which plan applies.
+	plan, err := models.GetPlan(ctx, inst.Deployment, in.Tier)
 	if err != nil {
 		return nil, ErrUnknownTier
 	}
@@ -67,11 +72,35 @@ func Issue(ctx context.Context, in IssueInput) (*models.License, error) {
 	}
 
 	if plan.Tier == license.TierFree {
-		if err := checkFreeLimit(ctx, inst.AccountID, inst.InstanceID); err != nil {
+		if err := checkFreeLimit(ctx, inst.AccountID, inst.Deployment, inst.InstanceID); err != nil {
 			return nil, err
 		}
 	}
 
+	// What this licence grants comes from the instance's entitlement, not from
+	// the plan. The plan is only the base.
+	//
+	// An instance with no entitlement gets the plan's base, which covers staff
+	// manual issuance and anything predating the backfill. Falling back is
+	// deliberate: refusing here would make a missing row an outage rather than a
+	// default.
+	limits, features := plan.BaseLimits, []string(plan.BaseFeatures.OrEmpty())
+	ent, entErr := models.GetEntitlement(ctx, inst.InstanceID)
+	switch {
+	case entErr == nil:
+		// Granted, never Desired. A configuration nobody has paid for must not
+		// reach a signed payload.
+		limits, features, err = catalogue.Resolve(ctx, plan, ent.Granted)
+		if err != nil {
+			return nil, fmt.Errorf("resolve entitlement: %w", err)
+		}
+	case errors.Is(entErr, models.ErrNoEntitlement):
+		log.Printf("licensing: instance %s has no entitlement; issuing plan base",
+			inst.InstanceID)
+	default:
+		return nil, fmt.Errorf("read entitlement: %w", entErr)
+	}
+
 	now := time.Now().UTC()
 	expires := in.ExpiresAt
 	if expires.IsZero() {
@@ -94,10 +123,11 @@ func Issue(ctx context.Context, in IssueInput) (*models.License, error) {
 		Deployment:   plan.Deployment,
 		IssuedAt:     now,
 		ExpiresAt:    expires,
-		// Snapshotted, not referenced: editing a plan tomorrow must not change
-		// what this licence grants.
-		Limits:   plan.Limits,
-		Features: plan.Features.OrEmpty(),
+		// Snapshotted, not referenced: editing a plan or an entitlement tomorrow
+		// must not change what this licence grants.
+		Limits:       limits,
+		Features:     features,
+		SupportLevel: plan.SupportLevel,
 	}
 
 	blob, err := license.Sign(payload, signingKey)
@@ -111,8 +141,8 @@ func Issue(ctx context.Context, in IssueInput) (*models.License, error) {
 		AccountID:  inst.AccountID,
 		Tier:       plan.Tier,
 		Deployment: plan.Deployment,
-		Limits:     plan.Limits,
-		Features:   plan.Features.OrEmpty(),
+		Limits:     limits,
+		Features:   models.Features(features).OrEmpty(),
 		IssuedAt:   now,
 		ExpiresAt:  expires,
 		Blob:       blob,
@@ -157,13 +187,19 @@ func Issue(ctx context.Context, in IssueInput) (*models.License, error) {
 	return &rec, nil
 }
 
-// checkFreeLimit enforces one Free instance per account.
+// checkFreeLimit enforces one Free instance per account PER DEPLOYMENT.
+//
+// It used to be one per account, which was sufficient while Free existed only on
+// cloud. With a self-hosted Free plan, an account-wide count would refuse a
+// self-hosted Free instance to anyone holding a cloud one, and tell them about a
+// limit they have not reached.
 //
 // Cancelled instances do not count: a customer who cancelled their Free instance
 // is allowed another one.
-func checkFreeLimit(ctx context.Context, accountID, exceptInstanceID string) error {
+func checkFreeLimit(ctx context.Context, accountID, deployment, exceptInstanceID string) error {
 	n, err := db.Admin("admin_instances").CountDocuments(ctx, bson.M{
 		"account_id":  accountID,
+		"deployment":  deployment,
 		"tier":        license.TierFree,
 		"status":      bson.M{"$ne": models.StatusCancelled},
 		"instance_id": bson.M{"$ne": exceptInstanceID},

admin/internal/models/backfill.go

@@ -97,5 +97,152 @@ func Backfill(ctx context.Context) error {
 	if created > 0 {
 		log.Printf("backfill: recorded %d pre-existing instance owners", created)
 	}
+
+	// Pass 3: plans were keyed on tier alone. Give the two cloud tiers their
+	// deployment, and turn the self_hosted TIER row into the self-hosted
+	// Professional row it always was. Field names move too: limits/features
+	// become base_limits/base_features, because "base" is a different claim.
+	if _, err := db.Admin("plans").UpdateMany(ctx,
+		bson.M{"deployment": bson.M{"$exists": false},
+			"tier": bson.M{"$in": bson.A{license.TierFree, license.TierProfessional}}},
+		bson.M{"$set": bson.M{"deployment": license.DeploymentCloud}}); err != nil {
+		return err
+	}
+	if _, err := db.Admin("plans").UpdateOne(ctx,
+		bson.M{"tier": license.TierSelfHosted},
+		bson.M{"$set": bson.M{
+			"deployment": license.DeploymentSelfHosted,
+			"tier":       license.TierProfessional,
+			"name":       "Professional",
+		}}); err != nil {
+		return err
+	}
+	if _, err := db.Admin("plans").UpdateMany(ctx,
+		bson.M{"limits": bson.M{"$exists": true}},
+		bson.M{"$rename": bson.M{"limits": "base_limits", "features": "base_features"}}); err != nil {
+		return err
+	}
+	// Support level is new, so nothing has one. Fill from the seed table rather
+	// than guessing: a plan row a human edited keeps every other field.
+	for _, deployment := range license.Deployments() {
+		for _, tier := range license.Tiers() {
+			p, ok := license.PlanFor(deployment, tier)
+			if !ok {
+				continue
+			}
+			if _, err := db.Admin("plans").UpdateOne(ctx,
+				bson.M{"deployment": deployment, "tier": tier,
+					"support_level": bson.M{"$in": bson.A{nil, ""}}},
+				bson.M{"$set": bson.M{"support_level": p.SupportLevel}}); err != nil {
+				return err
+			}
+		}
+	}
+
+	// Pass 4: instances carrying the self_hosted TIER move to Professional.
+	// Their deployment already says self_hosted, so only the tier is wrong.
+	res, err = db.Admin("admin_instances").UpdateMany(ctx,
+		bson.M{"tier": license.TierSelfHosted},
+		bson.M{"$set": bson.M{"tier": license.TierProfessional}})
+	if err != nil {
+		return err
+	}
+	if res.ModifiedCount > 0 {
+		log.Printf("backfill: re-tiered %d self-hosted instances to professional", res.ModifiedCount)
+	}
+
+	// Pass 5: give every instance an entitlement, reconstructed from its current
+	// licence. Filtering on the absence of a row is what makes this idempotent,
+	// and it means an entitlement a customer has since edited is never
+	// overwritten by a stale licence.
+	if err := backfillEntitlements(ctx); err != nil {
+		return err
+	}
 	return nil
 }
+
+// backfillEntitlements reconstructs an entitlement per instance from its licence.
+//
+// An Unlimited max_servers maps back to the plan's BASE allowance rather than to
+// a huge number: an unlimited licence bought no server units, so the honest
+// reconstruction of "how many did they pay for" is none. This makes a
+// pre-metering Professional instance read as 3 servers, which is a REDUCTION in
+// what it is allowed. That is deliberate and it is why this is a plan step and
+// not a silent fix — see the task's confirmation step.
+func backfillEntitlements(ctx context.Context) error {
+	cur, err := db.Admin("admin_instances").Find(ctx,
+		bson.M{"status": bson.M{"$ne": StatusDeleted}})
+	if err != nil {
+		return err
+	}
+	var instances []Instance
+	if err := cur.All(ctx, &instances); err != nil {
+		return err
+	}
+
+	created := 0
+	for _, inst := range instances {
+		n, err := db.Admin("entitlements").CountDocuments(ctx,
+			bson.M{"instance_id": inst.InstanceID})
+		if err != nil {
+			return err
+		}
+		if n > 0 {
+			continue
+		}
+
+		deployment, tier := license.NormaliseTier(inst.Deployment, inst.Tier)
+		if tier == "" {
+			// An instance awaiting its first licence has no tier. It gets an
+			// entitlement when one is issued, not before.
+			continue
+		}
+		plan, err := GetPlan(ctx, deployment, tier)
+		if err != nil {
+			log.Printf("backfill: instance %s names unknown plan %s/%s; skipped",
+				inst.InstanceID, deployment, tier)
+			continue
+		}
+
+		cfg := Config{Servers: plan.BaseLimits.MaxServers, Features: Features{}}
+		if inst.CurrentLicense != "" {
+			var lic License
+			if err := db.Admin("licenses").FindOne(ctx,
+				bson.M{"license_id": inst.CurrentLicense}).Decode(&lic); err == nil {
+				if lic.Limits.MaxServers != license.Unlimited && lic.Limits.MaxServers > 0 {
+					cfg.Servers = lic.Limits.MaxServers
+				}
+				cfg.Features = lic.Features.OrEmpty()
+			}
+		}
+
+		limits := plan.BaseLimits
+		limits.MaxServers = cfg.Servers
+		if err := UpsertEntitlement(ctx, Entitlement{
+			InstanceID:     inst.InstanceID,
+			AccountID:      inst.AccountID,
+			Deployment:     deployment,
+			Tier:           tier,
+			Term:           defaultTerm(deployment),
+			Desired:        cfg,
+			Granted:        cfg,
+			ResolvedLimits: limits,
+		}); err != nil {
+			return err
+		}
+		created++
+	}
+	if created > 0 {
+		log.Printf("backfill: created %d entitlements from current licences", created)
+	}
+	return nil
+}
+
+// defaultTerm is the term to assume for a reconstructed entitlement. Self-hosted
+// sells annual only, so there is nothing to guess there.
+func defaultTerm(deployment string) string {
+	if deployment == license.DeploymentSelfHosted {
+		return "annual"
+	}
+	return "monthly"
+}

admin/internal/models/catalogue.go

@@ -0,0 +1,140 @@
+package models
+
+import (
+	"context"
+
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/shared/license"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+// Component kinds.
+const (
+	// KindBase is the plan's own fee, always quantity 1.
+	KindBase = "base"
+	// KindLimit raises a named limit by one per unit of quantity.
+	KindLimit = "limit"
+	// KindFeature is an on/off feature key.
+	KindFeature = "feature"
+)
+
+// LimitKeyServers is the only metered limit today.
+//
+// A limit_key is a field name in license.Limits, which is what lets a second
+// metered dimension be a catalogue row rather than a code change. There is
+// deliberately no block size: with secret-group blocks dropped from the spec it
+// would be 1 in every row that will ever exist.
+const LimitKeyServers = "max_servers"
+
+// CatalogueRow is one priceable component of one plan.
+//
+// This is the ONLY place a Paddle price ID appears anywhere in Vantage. An empty
+// PriceIDs means the component is free — a feature with no price is a toggle a
+// customer may take at no charge, and giving it a price later is a staff edit
+// rather than a migration or a deploy.
+type CatalogueRow struct {
+	ID         bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	Kind       string        `bson:"kind" json:"kind"`
+	Deployment string        `bson:"deployment" json:"deployment"`
+	Tier       string        `bson:"tier" json:"tier"`
+	LimitKey   string        `bson:"limit_key,omitempty" json:"limit_key,omitempty"`
+	FeatureKey string        `bson:"feature_key,omitempty" json:"feature_key,omitempty"`
+	// PriceIDs is environment -> term -> Paddle price ID, e.g.
+	// {"sandbox": {"monthly": "pri_…"}, "production": {"annual": "pri_…"}}.
+	//
+	// Nested by environment rather than kept in two collections, because
+	// promoting sandbox to production must be a configuration change and not a
+	// data migration. The running PADDLE_ENV picks the inner map.
+	PriceIDs map[string]map[string]string `bson:"price_ids,omitempty" json:"price_ids,omitempty"`
+}
+
+// PriceID returns the price for one environment and term, or "".
+func (r CatalogueRow) PriceID(env, term string) string {
+	if r.PriceIDs == nil {
+		return ""
+	}
+	return r.PriceIDs[env][term]
+}
+
+// Priced reports whether this component costs anything in an environment.
+func (r CatalogueRow) Priced(env string) bool {
+	for _, term := range []string{"monthly", "annual"} {
+		if r.PriceID(env, term) != "" {
+			return true
+		}
+	}
+	return false
+}
+
+// SeedCatalogue inserts the sixteen rows the four PAID plans need.
+//
+// The two Free plans get no rows at all, and that absence is what keeps Free
+// outside Paddle: with nothing to price, no checkout can be built for it. Do not
+// "fix" this by adding zero-priced Free rows.
+//
+// $setOnInsert only, for the same reason as SeedPlans: the price IDs are pasted
+// in by staff and a redeploy must not blank them.
+func SeedCatalogue(ctx context.Context) error {
+	paid := []string{license.TierProfessional, license.TierEnterprise}
+	for _, deployment := range license.Deployments() {
+		for _, tier := range paid {
+			rows := []CatalogueRow{
+				{Kind: KindBase, Deployment: deployment, Tier: tier},
+				{Kind: KindLimit, Deployment: deployment, Tier: tier, LimitKey: LimitKeyServers},
+				{Kind: KindFeature, Deployment: deployment, Tier: tier, FeatureKey: license.FeatureConsole},
+				{Kind: KindFeature, Deployment: deployment, Tier: tier, FeatureKey: license.FeatureOIDC},
+			}
+			for _, r := range rows {
+				filter := bson.M{
+					"kind":        r.Kind,
+					"deployment":  r.Deployment,
+					"tier":        r.Tier,
+					"limit_key":   r.LimitKey,
+					"feature_key": r.FeatureKey,
+				}
+				if _, err := db.Admin("catalogue").UpdateOne(ctx, filter,
+					bson.M{"$setOnInsert": bson.M{
+						"kind":        r.Kind,
+						"deployment":  r.Deployment,
+						"tier":        r.Tier,
+						"limit_key":   r.LimitKey,
+						"feature_key": r.FeatureKey,
+						"price_ids":   map[string]map[string]string{},
+					}},
+					options.UpdateOne().SetUpsert(true)); err != nil {
+					return err
+				}
+			}
+		}
+	}
+	return nil
+}
+
+// CatalogueFor returns every component of one plan.
+func CatalogueFor(ctx context.Context, deployment, tier string) ([]CatalogueRow, error) {
+	deployment, tier = license.NormaliseTier(deployment, tier)
+	cur, err := db.Admin("catalogue").Find(ctx,
+		bson.M{"deployment": deployment, "tier": tier})
+	if err != nil {
+		return nil, err
+	}
+	rows := []CatalogueRow{}
+	if err := cur.All(ctx, &rows); err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+// AllCatalogue returns every row, for the staff editor.
+func AllCatalogue(ctx context.Context) ([]CatalogueRow, error) {
+	cur, err := db.Admin("catalogue").Find(ctx, bson.M{})
+	if err != nil {
+		return nil, err
+	}
+	rows := []CatalogueRow{}
+	if err := cur.All(ctx, &rows); err != nil {
+		return nil, err
+	}
+	return rows, nil
+}

admin/internal/models/entitlements.go

@@ -0,0 +1,139 @@
+package models
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/mrhid6/vantage/admin/internal/db"
+	"github.com/mrhid6/vantage/shared/license"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+// ErrNoEntitlement means the instance has no configuration row.
+//
+// Callers fall back to the plan's base rather than failing: staff manual
+// issuance and any instance predating the backfill legitimately have none.
+var ErrNoEntitlement = errors.New("instance has no entitlement")
+
+// Config is one side of an entitlement — a complete statement of what an
+// instance is allowed.
+//
+// Servers is the TOTAL the customer sees, not the number of units billed. The
+// billed quantity is Servers minus the plan's base allowance, and it is computed
+// where the line items are built rather than stored, so the two can never
+// disagree about which of them included the base.
+type Config struct {
+	Servers  int      `bson:"servers" json:"servers"`
+	Features Features `bson:"features" json:"features"`
+}
+
+// Entitlement is what one instance's customer configured.
+//
+// Both the subscription and the licence are derived from it; it is derived from
+// nothing. Desired is what they last asked for; Granted is what a payment
+// confirmed. A licence is only ever signed from Granted, so an abandoned
+// checkout leaves a Desired that reached nothing.
+type Entitlement struct {
+	ID         bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	InstanceID string        `bson:"instance_id" json:"instance_id"`
+	AccountID  string        `bson:"account_id" json:"account_id"`
+	Deployment string        `bson:"deployment" json:"deployment"`
+	Tier       string        `bson:"tier" json:"tier"`
+	Term       string        `bson:"term" json:"term"`
+
+	Desired Config `bson:"desired" json:"desired"`
+	Granted Config `bson:"granted" json:"granted"`
+
+	// ResolvedLimits is BaseLimits with Granted folded in. It is stored rather
+	// than derived on read so the fold lives in exactly one place — deriving it
+	// at every read would put the arithmetic in the issuer, the portal and the
+	// staff console.
+	ResolvedLimits license.Limits `bson:"resolved_limits" json:"resolved_limits"`
+
+	// ScheduledChangeAt is when a pending REDUCTION takes effect. It is set only
+	// when Desired grants less than Granted, and it is what lets the portal say
+	// "drops to 5 on 12 August" instead of guessing.
+	ScheduledChangeAt *time.Time `bson:"scheduled_change_at,omitempty" json:"scheduled_change_at,omitempty"`
+
+	GrantedAt time.Time `bson:"granted_at" json:"granted_at"`
+	UpdatedAt time.Time `bson:"updated_at" json:"updated_at"`
+}
+
+// Pending reports whether Desired and Granted disagree.
+func (e Entitlement) Pending() bool {
+	if e.Desired.Servers != e.Granted.Servers {
+		return true
+	}
+	if len(e.Desired.Features) != len(e.Granted.Features) {
+		return true
+	}
+	have := map[string]bool{}
+	for _, f := range e.Granted.Features {
+		have[f] = true
+	}
+	for _, f := range e.Desired.Features {
+		if !have[f] {
+			return true
+		}
+	}
+	return false
+}
+
+// GetEntitlement reads one instance's configuration.
+func GetEntitlement(ctx context.Context, instanceID string) (*Entitlement, error) {
+	var e Entitlement
+	err := db.Admin("entitlements").FindOne(ctx,
+		bson.M{"instance_id": instanceID}).Decode(&e)
+	if errors.Is(err, mongo.ErrNoDocuments) {
+		return nil, ErrNoEntitlement
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &e, nil
+}
+
+// UpsertEntitlement writes an entitlement, creating it if absent.
+//
+// GrantedAt is only touched when Granted actually changes, which is what makes
+// it answer "since when has this instance been allowed this" rather than "when
+// was this row last written".
+func UpsertEntitlement(ctx context.Context, e Entitlement) error {
+	now := time.Now().UTC()
+	set := bson.M{
+		"account_id":      e.AccountID,
+		"deployment":      e.Deployment,
+		"tier":            e.Tier,
+		"term":            e.Term,
+		"desired":         e.Desired,
+		"granted":         e.Granted,
+		"resolved_limits": e.ResolvedLimits,
+		"updated_at":      now,
+	}
+	if e.ScheduledChangeAt != nil {
+		set["scheduled_change_at"] = *e.ScheduledChangeAt
+	}
+	if !e.GrantedAt.IsZero() {
+		set["granted_at"] = e.GrantedAt
+	} else {
+		set["granted_at"] = now
+	}
+	update := bson.M{"$set": set}
+	if e.ScheduledChangeAt == nil {
+		update["$unset"] = bson.M{"scheduled_change_at": ""}
+	}
+	_, err := db.Admin("entitlements").UpdateOne(ctx,
+		bson.M{"instance_id": e.InstanceID},
+		mergeSetOnInsert(update, bson.M{"instance_id": e.InstanceID}),
+		options.UpdateOne().SetUpsert(true))
+	return err
+}
+
+// mergeSetOnInsert adds a $setOnInsert clause without clobbering an existing one.
+func mergeSetOnInsert(update bson.M, onInsert bson.M) bson.M {
+	update["$setOnInsert"] = onInsert
+	return update
+}

admin/internal/models/models.go

@@ -68,6 +68,13 @@ const (
 	ReasonTierChange = "tier_change"
 	ReasonRelink     = "relink"
 	ReasonManual     = "manual"
+
+	// ReasonEntitlementChange is a mid-term change to what an instance is
+	// allowed — servers added, a feature toggled — at the same expiry.
+	//
+	// It is deliberately NOT ReasonRenewal: a renewal resets relink_count
+	// because a new term has begun, and adding a server does not begin one.
+	ReasonEntitlementChange = "entitlement_change"
 )
 
 // MaxRelinksPerTerm is the customer-facing relink cap.
@@ -158,21 +165,28 @@ type Subscription struct {
 	CurrentPeriodEnd     time.Time     `bson:"current_period_end" json:"current_period_end"`
 }
 
-// Plan is the authoritative tier definition, seeded from shared/license.
+// Plan is the authoritative definition of one (deployment, tier) pair, seeded
+// from shared/license.
 //
 // It lives in the database so tier contents change without a deploy. Every
 // issued licence snapshots it, so editing a plan never rewrites an existing
 // licence — the same rule as workflow_runs.steps_snapshot.
+//
+// It holds NO Paddle identifiers. Every price ID lives in `catalogue`, because a
+// metered plan is priced by several components and a single map on this row
+// cannot express that.
 type Plan struct {
-	ID              bson.ObjectID     `bson:"_id,omitempty" json:"-"`
-	Tier            string            `bson:"tier" json:"tier"`
-	Name            string            `bson:"name" json:"name"`
-	Deployment      string            `bson:"deployment" json:"deployment"`
-	Limits          license.Limits    `bson:"limits" json:"limits"`
-	Features        Features          `bson:"features" json:"features"`
-	PaddleProductID string            `bson:"paddle_product_id,omitempty" json:"paddle_product_id,omitempty"`
-	PaddlePriceIDs  map[string]string `bson:"paddle_price_ids,omitempty" json:"paddle_price_ids,omitempty"`
-	Active          bool              `bson:"active" json:"active"`
+	ID         bson.ObjectID `bson:"_id,omitempty" json:"-"`
+	Deployment string        `bson:"deployment" json:"deployment"`
+	Tier       string        `bson:"tier" json:"tier"`
+	Name       string        `bson:"name" json:"name"`
+	// BaseLimits is the allowance before anything is bought. The field is named
+	// `base_` rather than `limits` because that is a different claim from the one
+	// the old field made, and a reader must not assume it is the total.
+	BaseLimits   license.Limits `bson:"base_limits" json:"base_limits"`
+	BaseFeatures Features       `bson:"base_features" json:"base_features"`
+	SupportLevel string         `bson:"support_level" json:"support_level"`
+	Active       bool           `bson:"active" json:"active"`
 }
 
 type StaffUser struct {

admin/internal/models/plans.go

@@ -10,38 +10,48 @@ import (
 	"go.mongodb.org/mongo-driver/v2/mongo/options"
 )
 
-// SeedPlans inserts the tier table from shared/license on first boot.
+// SeedPlans inserts the six (deployment, tier) rows from shared/license on first
+// boot.
 //
-// It uses $setOnInsert only: once a plan exists, staff edits to limits, features
-// and Paddle IDs are authoritative and a redeploy must not stamp over them.
+// It uses $setOnInsert only: once a plan exists, staff edits to allowances,
+// features and support level are authoritative and a redeploy must not stamp
+// over them.
 func SeedPlans(ctx context.Context) error {
-	for _, tier := range []string{license.TierFree, license.TierProfessional, license.TierSelfHosted} {
-		p, ok := license.PlanFor(tier)
-		if !ok {
-			continue
-		}
-		_, err := db.Admin("plans").UpdateOne(ctx,
-			bson.M{"tier": tier},
-			bson.M{"$setOnInsert": bson.M{
-				"tier":       p.Tier,
-				"name":       p.Name,
-				"deployment": p.Deployment,
-				"limits":     p.Limits,
-				"features":   Features(p.Features).OrEmpty(),
-				"active":     true,
-			}},
-			options.UpdateOne().SetUpsert(true))
-		if err != nil {
-			return err
+	for _, deployment := range license.Deployments() {
+		for _, tier := range license.Tiers() {
+			p, ok := license.PlanFor(deployment, tier)
+			if !ok {
+				continue
+			}
+			_, err := db.Admin("plans").UpdateOne(ctx,
+				bson.M{"deployment": deployment, "tier": tier},
+				bson.M{"$setOnInsert": bson.M{
+					"deployment":    p.Deployment,
+					"tier":          p.Tier,
+					"name":          p.Name,
+					"base_limits":   p.Limits,
+					"base_features": Features(p.Features).OrEmpty(),
+					"support_level": p.SupportLevel,
+					"active":        true,
+				}},
+				options.UpdateOne().SetUpsert(true))
+			if err != nil {
+				return err
+			}
 		}
 	}
 	return nil
 }
 
-// GetPlan reads a tier's authoritative definition.
-func GetPlan(ctx context.Context, tier string) (*Plan, error) {
+// GetPlan reads one pair's authoritative definition.
+//
+// It normalises the tier first, so a legacy self_hosted licence being reissued
+// resolves to the plan that replaced it.
+func GetPlan(ctx context.Context, deployment, tier string) (*Plan, error) {
+	deployment, tier = license.NormaliseTier(deployment, tier)
 	var p Plan
-	if err := db.Admin("plans").FindOne(ctx, bson.M{"tier": tier}).Decode(&p); err != nil {
+	if err := db.Admin("plans").FindOne(ctx,
+		bson.M{"deployment": deployment, "tier": tier}).Decode(&p); err != nil {
 		return nil, err
 	}
 	return &p, nil