Entitlements & suites

What you can access in House is described by entitlements — grants held against your household (and, for member-private surfaces, against you as a member). This page explains the model and how a grant reaches a product.

Suites

A suite is a commercial grouping of product surface. A suite is a shape × vertical:

Suite	Shape	Tiers	Notes
vonkara	personal	Free → Starter → Pro	Vonkara’s per-room suite (no Premium rung — retired August 2026)
heldaro	personal	Free → Starter → Pro → Premium	Heldaro’s per-room suite
kragara	personal	Free → Starter → Pro → Premium	Kragara’s per-room suite

Free is simply the absence of a paid subscription for that room.

Grant keys

Entitlements are stored as value-less keys:

• Capability keys — cap:<product>:<feature>, e.g. cap:vonkara:pack-flow, cap:kragara:pack-adaptive, or cap:ai:use (the key that gates AI access). These answer “may I?”.
• Tier keys — tier:<suite>:<ordinal>, e.g. tier:vonkara:2 (Pro). These carry the billing ordinal for a suite.

Packs map to product features: a product’s house-mode resolver turns a cap:<product>:pack-* key into the internal feature flags it unlocks. Free-core features are the ones no pack claims.

Resolution — /_verify is authoritative

Entitlements are resolved from the database at request time, never trusted from a token claim:

1. The gateway strips every inbound identity header, then calls the identity service’s /_verify.
2. /_verify re-checks the live household and mints the identity + scope headers (X-House-Scopes, X-House-Suites, X-House-Principal, …) from current database state.
3. The gateway forwards those headers to the product.

If resolution fails, the request fails closed (401). A downgrade or cancellation strips the purchased grants; a grace hold keeps them for a defined window. This is why revoking access takes effect immediately — there is no long-lived entitlement baked into a token.

Delivery to products

A product never reads your entitlements from a JWT. It reads the gateway-injected headers, which are trustworthy because the gateway is the only thing allowed to set them (it strips any that arrive from the outside). See Billing for how grants are purchased.