@happyvertical/smrt-subscriptions 0.57.36 → 0.57.38

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-subscriptions",
-  "packageVersion": "0.57.36",
+  "packageVersion": "0.57.38",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "7017ffb293160b193e4224168747801f931d153ef8bc26f5482f2ad645132018",
-    "packageJson": "5ed31b2d6d6c34a704a9e83489532b29e67214e0dafc3e89db406bf9c7453e92",
-    "agents": "8d03287e49f241cfe3f1dac0a3bd32ffc51d67709c1e2af93e0368cd0cadaf02"
+    "manifest": "94e7379bed761a703b6586c351b3ec454c91ac9d5d73dc1815ebfe37199a7c65",
+    "packageJson": "6160c32f10c513b7f93f7d0a67b76a7fd0c45dbd44dcc7f2eec6e55f4de11321",
+    "agents": "5fcd3fec51594afb1d675ef3ea52aa239683416f0169fef8a96dfacaabb5580b"
   },
   "exports": [
     ".",
@@ -487,77 +487,88 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A short code that identifies the plan, such as starter or pro."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What the plan is called, as customers see it."
         },
         {
           "name": "description",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A sentence or two about what the plan offers."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "active"
+          "default": "active",
+          "description": "Whether the plan is a draft, on sale (active) or archived."
         },
         {
           "name": "sortOrder",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "Where the plan sits when plans are listed; lower numbers come first."
         },
         {
           "name": "priceAmount",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "What the plan costs each billing period, in cents, as a whole number."
         },
         {
           "name": "currency",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "USD"
+          "default": "USD",
+          "description": "The currency the price is in, such as USD."
         },
         {
           "name": "billingInterval",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "month"
+          "default": "month",
+          "description": "How often the subscriber is billed: every day, week, month or year."
         },
         {
           "name": "pricingMode",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "fixed"
+          "default": "fixed",
+          "description": "Whether the plan is free, has a fixed price, or lets the subscriber choose what to pay. It cannot change once the plan is saved."
         },
         {
           "name": "minimumAmount",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "For a pay-what-you-can plan, the least a subscriber may pay, in cents."
         },
         {
           "name": "suggestedAmount",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "For a pay-what-you-can plan, the amount suggested to the subscriber, in cents."
         },
         {
           "name": "externalProvider",
@@ -961,83 +972,95 @@
           "type": "foreignKey",
           "required": false,
           "related": "SubscriptionPlan",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The plan this version belongs to."
         },
         {
           "name": "planKey",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The plan code at the time this version was published."
         },
         {
           "name": "version",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "Which version of the plan this is, counting from 1."
         },
         {
           "name": "effectiveFrom",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "The date and time from which these terms apply."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What the plan was called when this version was published."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "active"
+          "default": "active",
+          "description": "Whether the plan was a draft, on sale (active) or archived under this version."
         },
         {
           "name": "priceAmount",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "What the plan cost each billing period under this version, in cents."
         },
         {
           "name": "currency",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "USD"
+          "default": "USD",
+          "description": "The currency the price is in, such as USD."
         },
         {
           "name": "billingInterval",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "month"
+          "default": "month",
+          "description": "How often the subscriber was billed: every day, week, month or year."
         },
         {
           "name": "pricingMode",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "fixed"
+          "default": "fixed",
+          "description": "Whether the plan was free, had a fixed price, or let the subscriber choose what to pay."
         },
         {
           "name": "minimumAmount",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "For a pay-what-you-can plan, the least a subscriber could pay, in cents."
         },
         {
           "name": "suggestedAmount",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "For a pay-what-you-can plan, the amount suggested to the subscriber, in cents."
         },
         {
           "name": "features",
@@ -1206,78 +1229,90 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "tenant"
+          "default": "tenant",
+          "description": "Whether the subscriber is your own workspace (tenant) or an outside customer (external)."
         },
         {
           "name": "subscriberExternalId",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Who the outside subscriber is, when the subscriber type is external."
         },
         {
           "name": "planId",
           "type": "foreignKey",
           "required": false,
           "related": "SubscriptionPlan",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The plan this subscription is for."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "incomplete"
+          "default": "incomplete",
+          "description": "Where the subscription stands: incomplete, trialing, active, past due, unpaid or cancelled."
         },
         {
           "name": "startedAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "The day the subscription began."
         },
         {
           "name": "currentPeriodStart",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When the current billing period began."
         },
         {
           "name": "currentPeriodEnd",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When the current billing period ends and the next one is due."
         },
         {
           "name": "trialEndsAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When the free trial ends, if there is one."
         },
         {
           "name": "cancelAtPeriodEnd",
           "type": "boolean",
           "required": false,
           "columnType": "BOOLEAN",
-          "default": false
+          "default": false,
+          "description": "Tick to let the subscription run out at the end of the current period instead of renewing."
         },
         {
           "name": "canceledAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When the subscription was cancelled."
         },
         {
           "name": "agreedAmount",
           "type": "integer",
           "required": false,
-          "columnType": "INTEGER"
+          "columnType": "INTEGER",
+          "description": "For a pay-what-you-can plan, the amount the subscriber chose to pay, in cents."
         },
         {
           "name": "planVersionId",
           "type": "foreignKey",
           "required": false,
           "related": "SubscriptionPlanVersion",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The version of the plan terms this subscription is held to for the current period. It is kept up to date automatically."
         },
         {
           "name": "planVersionPinnedAt",
@@ -2120,42 +2155,48 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Who supplied the service that was used."
         },
         {
           "name": "serviceKey",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The service that was used."
         },
         {
           "name": "metricKey",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What was used, such as messages sent or minutes of audio."
         },
         {
           "name": "quantity",
           "type": "decimal",
           "required": false,
           "columnType": "REAL",
-          "default": 0
+          "default": 0,
+          "description": "How much of it was used."
         },
         {
           "name": "amount",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "What it cost, in cents."
         },
         {
           "name": "currency",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "USD"
+          "default": "USD",
+          "description": "The currency the amount is in, such as USD."
         },
         {
           "name": "pricingRuleId",
@@ -2183,13 +2224,15 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "draft"
+          "default": "draft",
+          "description": "Where the charge stands: draft, approved or adjusted."
         },
         {
           "name": "approvedAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When the charge was approved."
         }
       ],
       "relationships": [
@@ -4187,7 +4230,380 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 88
   },
-  "agentDoc": "# @happyvertical/smrt-subscriptions\n\nTenant subscriptions, plan features, immutable/idempotent usage evidence,\neffective-dated client pricing, scoped spending policies, and entitlement\nresolution for SMRT applications.\n\n## Validation\n\n```bash\npnpm --filter @happyvertical/smrt-subscriptions test\npnpm --filter @happyvertical/smrt-subscriptions test:postgres\npnpm --filter @happyvertical/smrt-subscriptions typecheck\npnpm --filter @happyvertical/smrt-subscriptions build\n```\n\n`test:postgres` is the lane that holds the money-column line — SQLite's type\naffinity stores a REAL in an INTEGER column without complaint, so a money field\nthat reverted to DECIMAL passes every SQLite suite.\n\n## Money\n\n- **Money is integer minor units** (cents) — `$19.99` is `1999`.\n  `SubscriptionPlan.priceAmount`, `ClientCharge.amount`, `RetailCharge.amount`,\n  `CreditGrant.amount`,\n  `BillingAdjustment.amount` and `SpendingPolicy.limitAmount` all initialize\n  `= 0`, never `= 0.0`: the integer literal is what maps them to INTEGER\n  columns (BIGINT on fresh PostgreSQL/DuckDB databases; #2401, #2373). `ClientCharge.quantity` and `TenantUsageMetric.quantity` are\n  the opposite case — metered quantities are genuinely fractional and stay\n  DECIMAL.\n- **`PricingRule.terms` are minor units *per unit of usage*, and stay\n  fractional.** A per-token rate is routinely a fraction of a cent, so an\n  integer `unitPrice` would truncate it to zero. `calculateAmount()` rounds the\n  computed result to a whole minor unit — that is the single boundary in the\n  package where a rate meets money, and it is what lets `evaluateSpending()`\n  compare charge sums against `limitAmount` exactly.\n- **`adjust()` rejects a fractional amount.** Negative amounts are legitimate\n  (a credit); fractional ones almost always mean the caller passed major units.\n- **Billing rejects immediate JSON write-back.** The JSON adapter's default\n  `writeStrategy: 'immediate'` and DuckDB with that write-back strategy export\n  files before transaction commit, while adapter rollback restores only the\n  database transaction. `CommercialUsageService` therefore fails before setup\n  on those configurations. PostgreSQL, SQLite, ordinary DuckDB, and explicit\n  non-immediate write strategies remain supported. When supplying an already\n  resolved database handle, also pass `billingStorage` so this capability\n  decision is explicit rather than inferred from private adapter state.\n- **Embedded sourced adjustments serialize per database.** SQLite, DuckDB, and\n  supported non-immediate JSON handles multiplex local writes; the complete\n  deterministic adjustment flow, including recovery reads, runs under one\n  database-scoped lock. Every supported embedded adjustment transaction,\n  sourced or unsourced, also holds the core embedded write queue for its full\n  lifetime; transaction-bound model saves re-enter that hold so adjustments\n  cannot absorb, roll back, or deadlock with unrelated ordinary writes.\n- **UI formats by dividing, never by `toFixed`.** `PlanPicker` and\n  `CommercialOverview` scale back to major units using the currency's own\n  minor-unit exponent, so zero-decimal currencies (JPY, KRW) are not divided.\n- **Migrating an existing database**: `preflightSubscriptionsMoneyMinorUnits(db)`\n  reports which columns still hold major units and which rows would be rounded\n  or exceed JavaScript's safe-integer range; `migrateSubscriptionsMoneyToMinorUnits(db)` converts them\n  (idempotent via `_smrt_backfills`). On SQLite the values are rescaled but the\n  declared type needs the table-rebuild path (#2370). Existing\n  `PricingRule.terms` are **not** migrated automatically — only the operator\n  knows which keys in a given rule are prices rather than quantities or ratios.\n- **Range and existing deployments**: fresh PostgreSQL/DuckDB INTEGER columns\n  are BIGINT, and hydration rejects values outside JavaScript's safe-integer\n  range. Existing PostgreSQL `int4` columns require the explicit widening in #2424.\n\n## Plan versions (#4032)\n\n- `SubscriptionPlan.save()` publishes the next immutable\n  `SubscriptionPlanVersion` when its terms (`PLAN_TERM_FIELDS`) change; the\n  logic lives in `src/plan-versioning.ts`. Versions are append-only,\n  contiguous, and monotonic in `effectiveFrom`.\n- `TenantSubscription.validateBeforeSave()` maintains `planVersionId` via\n  `pinSubscriptionPlanVersion()`: pin at period start, re-pin when\n  `currentPeriodStart` moves, and refuse in-period changes that are not an\n  `isEntitlementUpgrade()` unless `replacePlanVersion({ policy: 'authorized',\n  reason })`. Never relax this to \"latest version wins\": a paid period must\n  not lose entitlements.\n- The resolver reads the pinned version; a missing or inactive pinned version\n  fails closed. Only unpinned rows on plans without versions fall back to the\n  live plan. `migrateSubscriptionPlanVersions(db)` backfills both.\n- Renewal means the new `currentPeriodStart` is at or after the stored\n  `currentPeriodEnd`; creation and renewal pin the boundary's version, and a\n  caller-named other version needs an authorized replacement.\n- `canceled` subscriptions entitle until `currentPeriodEnd` only with\n  `retainsPaidPeriod`, derived on save from an entitled pre-cancel row.\n\n## Reseller billing (#3059)\n\n- Billing ownership is consumed from `smrt-tenancy`'s\n  `BillingRelationshipService` (`BillingRelationshipReader`); never re-derive\n  parentage or owners here.\n- `ClientCharge` stays one row per usage event (`usage_event_id` unique) and\n  `tenantId` is always the payer. That uniqueness is the double-billing guard\n  across owner changes; do not widen its conflict key. The retail leg lives in\n  `RetailCharge` (also one per event), written in the same transaction.\n- Price-book rules are `PricingRule` rows with `priceBookId`; `price()` must\n  keep ignoring them, and `rateUsage()` only trusts rules whose tenant owns the\n  book.\n- Delegated `SpendingPolicy` rows (`setByTenantId`) are guarded in\n  `validateBeforeSave` and a `beforeDelete` hook, by id and by conflict key;\n  `CreditGrant` applies the same parent-only rule to delegated balances.\n  `PriceBookAssignmentCollection` is deliberately not a root export.\n- `ResellerBillingService` authorizes first, then writes in a system context\n  (parent writes land on child-owned rows). The wholesale leg is authorized by\n  the book's publisher and may never be published by the payer; whether a\n  publisher is a legitimate provider for the reseller is a host obligation\n  (the model records no upstream seller). Relationship reads precede\n  authorization and stay under smrt-tenancy's own read rules. The only\n  cross-tenant read in evaluation is the bounded `wholesale`-basis sum.\n- `balance` policies take their limit from `CreditGrant`s; `limitAmount` must\n  be 0, and currency and period are fixed once saved (the ledger is scoped to\n  them). Auto top-up is a host hook only — no payment provider calls. The\n  evaluator re-reads credit after the hook returns (grant or not) and hands\n  it `currentShortfall()`, so a hook that charges asynchronously can see a\n  concurrent top-up (smrt-commerce's `autoTopUpHook()`, #3139).\n\n## Notes\n\n- Keep Stripe-specific fields as provider binding metadata. Runtime Stripe API\n  calls belong in the HappyVertical SDK accounting provider.\n- Thresholds are evaluated from tenant usage metrics and optional AI usage\n  summaries. Resolve multiple thresholds with the batch usage path where\n  available; do not bypass tenant context in application code.\n- Use `SubscriptionResolver.create()` or an explicitly injected\n  `SubscriptionResolver` once per request when resolving entitlements multiple\n  times. Load and pass `EntitlementResolutionContext` to avoid re-reading the\n  current subscription and plan.\n- Subscription UI components should stay provider-neutral and receive actions\n  from the host app.\n",
+  "agentDoc": "# @happyvertical/smrt-subscriptions\n\nTenant subscriptions, plan features, immutable/idempotent usage evidence,\neffective-dated client pricing, scoped spending policies, and entitlement\nresolution for SMRT applications.\n\n## Validation\n\n```bash\npnpm --filter @happyvertical/smrt-subscriptions test\npnpm --filter @happyvertical/smrt-subscriptions test:postgres\npnpm --filter @happyvertical/smrt-subscriptions typecheck\npnpm --filter @happyvertical/smrt-subscriptions build\n```\n\n`test:postgres` is the lane that holds the money-column line — SQLite's type\naffinity stores a REAL in an INTEGER column without complaint, so a money field\nthat reverted to DECIMAL passes every SQLite suite.\n\n## Money\n\n- **Money is integer minor units** (cents) — `$19.99` is `1999`.\n  `SubscriptionPlan.priceAmount`, `ClientCharge.amount`, `RetailCharge.amount`,\n  `CreditGrant.amount`,\n  `BillingAdjustment.amount` and `SpendingPolicy.limitAmount` all initialize\n  `= 0`, never `= 0.0`: the integer literal is what maps them to INTEGER\n  columns (BIGINT on fresh PostgreSQL/DuckDB databases; #2401, #2373). `ClientCharge.quantity` and `TenantUsageMetric.quantity` are\n  the opposite case — metered quantities are genuinely fractional and stay\n  DECIMAL.\n- **`PricingRule.terms` are minor units *per unit of usage*, and stay\n  fractional.** A per-token rate is routinely a fraction of a cent, so an\n  integer `unitPrice` would truncate it to zero. `calculateAmount()` rounds the\n  computed result to a whole minor unit — that is the single boundary in the\n  package where a rate meets money, and it is what lets `evaluateSpending()`\n  compare charge sums against `limitAmount` exactly.\n- **`adjust()` rejects a fractional amount.** Negative amounts are legitimate\n  (a credit); fractional ones almost always mean the caller passed major units.\n- **Billing rejects immediate JSON write-back.** The JSON adapter's default\n  `writeStrategy: 'immediate'` and DuckDB with that write-back strategy export\n  files before transaction commit, while adapter rollback restores only the\n  database transaction. `CommercialUsageService` therefore fails before setup\n  on those configurations. PostgreSQL, SQLite, ordinary DuckDB, and explicit\n  non-immediate write strategies remain supported. When supplying an already\n  resolved database handle, also pass `billingStorage` so this capability\n  decision is explicit rather than inferred from private adapter state.\n- **Embedded sourced adjustments serialize per database.** SQLite, DuckDB, and\n  supported non-immediate JSON handles multiplex local writes; the complete\n  deterministic adjustment flow, including recovery reads, runs under one\n  database-scoped lock. Every supported embedded adjustment transaction,\n  sourced or unsourced, also holds the core embedded write queue for its full\n  lifetime; transaction-bound model saves re-enter that hold so adjustments\n  cannot absorb, roll back, or deadlock with unrelated ordinary writes.\n- **UI formats by dividing, never by `toFixed`.** `PlanPicker` and\n  `CommercialOverview` scale back to major units using the currency's own\n  minor-unit exponent, so zero-decimal currencies (JPY, KRW) are not divided.\n- **Migrating an existing database**: `preflightSubscriptionsMoneyMinorUnits(db)`\n  reports which columns still hold major units and which rows would be rounded\n  or exceed JavaScript's safe-integer range; `migrateSubscriptionsMoneyToMinorUnits(db)` converts them\n  (idempotent via `_smrt_backfills`). On SQLite the values are rescaled but the\n  declared type needs the table-rebuild path (#2370). Existing\n  `PricingRule.terms` are **not** migrated automatically — only the operator\n  knows which keys in a given rule are prices rather than quantities or ratios.\n- **Range and existing deployments**: fresh PostgreSQL/DuckDB INTEGER columns\n  are BIGINT, and hydration rejects values outside JavaScript's safe-integer\n  range. Existing PostgreSQL `int4` columns require the explicit widening in #2424.\n\n## Plan versions (#4032)\n\n- `SubscriptionPlan.save()` publishes the next immutable\n  `SubscriptionPlanVersion` when its terms (`PLAN_TERM_FIELDS`) change; the\n  logic lives in `src/plan-versioning.ts`. Versions are append-only,\n  contiguous, and monotonic in `effectiveFrom`.\n- `TenantSubscription.validateBeforeSave()` maintains `planVersionId` via\n  `pinSubscriptionPlanVersion()`: pin at period start, re-pin when\n  `currentPeriodStart` moves, and refuse in-period changes that are not an\n  `isEntitlementUpgrade()` unless `replacePlanVersion({ policy: 'authorized',\n  reason })`. Never relax this to \"latest version wins\": a paid period must\n  not lose entitlements.\n- The resolver reads the pinned version; a missing or inactive pinned version\n  fails closed. Only unpinned rows on plans without versions fall back to the\n  live plan. `migrateSubscriptionPlanVersions(db)` backfills both.\n- Renewal means the new `currentPeriodStart` is at or after the stored\n  `currentPeriodEnd`; creation and renewal pin the boundary's version, and a\n  caller-named other version needs an authorized replacement.\n- `canceled` subscriptions entitle until `currentPeriodEnd` only with\n  `retainsPaidPeriod`, derived on save from an entitled pre-cancel row.\n- **Recipe `subscriptions.plans`** (`src/recipes.ts`, help in `src/plans.recipe.md`): lists plans, subscriptions, plan versions (read-only, written by `plan-versioning.ts`) and charges (read-only, written by the usage service) for the planner and other catalog hosts. Fields it shows carry `@field({ description })` in plain words, money fields saying \"in cents\"; keep them when editing the models. Reseller models and pricing rules stay out of it.\n\n## Reseller billing (#3059)\n\n- Billing ownership is consumed from `smrt-tenancy`'s\n  `BillingRelationshipService` (`BillingRelationshipReader`); never re-derive\n  parentage or owners here.\n- `ClientCharge` stays one row per usage event (`usage_event_id` unique) and\n  `tenantId` is always the payer. That uniqueness is the double-billing guard\n  across owner changes; do not widen its conflict key. The retail leg lives in\n  `RetailCharge` (also one per event), written in the same transaction.\n- Price-book rules are `PricingRule` rows with `priceBookId`; `price()` must\n  keep ignoring them, and `rateUsage()` only trusts rules whose tenant owns the\n  book.\n- Delegated `SpendingPolicy` rows (`setByTenantId`) are guarded in\n  `validateBeforeSave` and a `beforeDelete` hook, by id and by conflict key;\n  `CreditGrant` applies the same parent-only rule to delegated balances.\n  `PriceBookAssignmentCollection` is deliberately not a root export.\n- `ResellerBillingService` authorizes first, then writes in a system context\n  (parent writes land on child-owned rows). The wholesale leg is authorized by\n  the book's publisher and may never be published by the payer; whether a\n  publisher is a legitimate provider for the reseller is a host obligation\n  (the model records no upstream seller). Relationship reads precede\n  authorization and stay under smrt-tenancy's own read rules. The only\n  cross-tenant read in evaluation is the bounded `wholesale`-basis sum.\n- `balance` policies take their limit from `CreditGrant`s; `limitAmount` must\n  be 0, and currency and period are fixed once saved (the ledger is scoped to\n  them). Auto top-up is a host hook only — no payment provider calls. The\n  evaluator re-reads credit after the hook returns (grant or not) and hands\n  it `currentShortfall()`, so a hook that charges asynchronously can see a\n  concurrent top-up (smrt-commerce's `autoTopUpHook()`, #3139).\n\n## Notes\n\n- Keep Stripe-specific fields as provider binding metadata. Runtime Stripe API\n  calls belong in the HappyVertical SDK accounting provider.\n- Thresholds are evaluated from tenant usage metrics and optional AI usage\n  summaries. Resolve multiple thresholds with the batch usage path where\n  available; do not bypass tenant context in application code.\n- Use `SubscriptionResolver.create()` or an explicitly injected\n  `SubscriptionResolver` once per request when resolving entitlements multiple\n  times. Load and pass `EntitlementResolutionContext` to avoid re-reading the\n  current subscription and plan.\n- Subscription UI components should stay provider-neutral and receive actions\n  from the host app.\n",
+  "recipes": [
+    {
+      "id": "subscriptions.plans",
+      "className": "SubscriptionPlansRecipe",
+      "label": "Subscriptions",
+      "summary": "Sell plans that renew, see who is subscribed to which, and what their usage cost.",
+      "synonyms": [
+        "subscriptions",
+        "subscription plans",
+        "plans",
+        "memberships",
+        "recurring billing",
+        "pricing tiers"
+      ],
+      "models": [
+        "@happyvertical/smrt-subscriptions:SubscriptionPlan",
+        "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion",
+        "@happyvertical/smrt-subscriptions:TenantSubscription",
+        "@happyvertical/smrt-subscriptions:ClientCharge"
+      ],
+      "nav": [
+        {
+          "label": "Plans",
+          "model": "@happyvertical/smrt-subscriptions:SubscriptionPlan",
+          "icon": "tag",
+          "description": "The plans you sell, with their price and how often they bill.",
+          "noun": "plan"
+        },
+        {
+          "label": "Subscriptions",
+          "model": "@happyvertical/smrt-subscriptions:TenantSubscription",
+          "icon": "repeat",
+          "description": "Who is subscribed to which plan, and where each one stands.",
+          "noun": "subscription"
+        },
+        {
+          "label": "Plan versions",
+          "model": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion",
+          "icon": "fileText",
+          "description": "Every set of terms a plan has had, and from when each applied.",
+          "noun": "plan version"
+        },
+        {
+          "label": "Charges",
+          "model": "@happyvertical/smrt-subscriptions:ClientCharge",
+          "icon": "receipt",
+          "description": "What each subscriber used and what it cost them.",
+          "noun": "charge"
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "sales",
+        "label": "Sales",
+        "icon": "shoppingBag",
+        "description": "Customers, orders and quotes: everything you sell."
+      },
+      "options": {
+        "@happyvertical/smrt-subscriptions:SubscriptionPlan": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "planKey": {
+              "label": "Plan code",
+              "order": 2
+            },
+            "description": {
+              "order": 3
+            },
+            "status": {
+              "order": 4
+            },
+            "priceAmount": {
+              "label": "Price (in cents)",
+              "order": 5
+            },
+            "currency": {
+              "order": 6
+            },
+            "billingInterval": {
+              "label": "Billed every",
+              "order": 7
+            },
+            "pricingMode": {
+              "label": "How it is priced",
+              "order": 8
+            },
+            "minimumAmount": {
+              "label": "Minimum (in cents)",
+              "visibility": "advanced"
+            },
+            "suggestedAmount": {
+              "label": "Suggested (in cents)",
+              "visibility": "advanced"
+            },
+            "sortOrder": {
+              "label": "Position in list",
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "features": {
+              "visibility": "hidden"
+            },
+            "thresholds": {
+              "visibility": "hidden"
+            },
+            "externalProvider": {
+              "visibility": "hidden"
+            },
+            "providerProductId": {
+              "visibility": "hidden"
+            },
+            "providerPriceId": {
+              "visibility": "hidden"
+            },
+            "stripeProductId": {
+              "visibility": "hidden"
+            },
+            "stripePriceId": {
+              "visibility": "hidden"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion": {
+          "fields": {
+            "planId": {
+              "label": "Plan",
+              "order": 1
+            },
+            "version": {
+              "label": "Version number",
+              "order": 2
+            },
+            "effectiveFrom": {
+              "label": "In force from",
+              "order": 3
+            },
+            "name": {
+              "order": 4
+            },
+            "status": {
+              "order": 5
+            },
+            "priceAmount": {
+              "label": "Price (in cents)",
+              "order": 6
+            },
+            "currency": {
+              "order": 7
+            },
+            "billingInterval": {
+              "label": "Billed every",
+              "order": 8
+            },
+            "planKey": {
+              "label": "Plan code",
+              "visibility": "advanced"
+            },
+            "pricingMode": {
+              "label": "How it is priced",
+              "visibility": "advanced"
+            },
+            "minimumAmount": {
+              "label": "Minimum (in cents)",
+              "visibility": "advanced"
+            },
+            "suggestedAmount": {
+              "label": "Suggested (in cents)",
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "features": {
+              "visibility": "hidden"
+            },
+            "thresholds": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-subscriptions:TenantSubscription": {
+          "fields": {
+            "planId": {
+              "label": "Plan",
+              "order": 1
+            },
+            "status": {
+              "order": 2
+            },
+            "startedAt": {
+              "label": "Started on",
+              "order": 3
+            },
+            "currentPeriodStart": {
+              "label": "Current period starts",
+              "order": 4
+            },
+            "currentPeriodEnd": {
+              "label": "Current period ends",
+              "order": 5
+            },
+            "trialEndsAt": {
+              "label": "Trial ends",
+              "order": 6
+            },
+            "cancelAtPeriodEnd": {
+              "label": "Cancel at end of period",
+              "order": 7
+            },
+            "canceledAt": {
+              "label": "Cancelled on",
+              "visibility": "advanced"
+            },
+            "agreedAmount": {
+              "label": "Agreed amount (in cents)",
+              "visibility": "advanced"
+            },
+            "subscriberKind": {
+              "label": "Subscriber type",
+              "visibility": "advanced"
+            },
+            "subscriberExternalId": {
+              "label": "Outside subscriber",
+              "visibility": "advanced"
+            },
+            "planVersionId": {
+              "label": "Plan version",
+              "visibility": "advanced",
+              "locked": true
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "planVersionPinnedAt": {
+              "visibility": "hidden"
+            },
+            "planVersionPinReason": {
+              "visibility": "hidden"
+            },
+            "planVersionPinNote": {
+              "visibility": "hidden"
+            },
+            "retainsPaidPeriod": {
+              "visibility": "hidden"
+            },
+            "externalProvider": {
+              "visibility": "hidden"
+            },
+            "stripeCustomerId": {
+              "visibility": "hidden"
+            },
+            "stripeSubscriptionId": {
+              "visibility": "hidden"
+            },
+            "stripeCheckoutSessionId": {
+              "visibility": "hidden"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-subscriptions:ClientCharge": {
+          "fields": {
+            "metricKey": {
+              "label": "What was used",
+              "order": 1
+            },
+            "quantity": {
+              "label": "How much",
+              "order": 2
+            },
+            "amount": {
+              "label": "Amount (in cents)",
+              "order": 3
+            },
+            "currency": {
+              "order": 4
+            },
+            "status": {
+              "order": 5
+            },
+            "approvedAt": {
+              "label": "Approved on",
+              "order": 6
+            },
+            "serviceKey": {
+              "label": "Service",
+              "visibility": "advanced"
+            },
+            "provider": {
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "usageEventId": {
+              "visibility": "hidden"
+            },
+            "usageTenantId": {
+              "visibility": "hidden"
+            },
+            "subscriberKind": {
+              "visibility": "hidden"
+            },
+            "subscriberExternalId": {
+              "visibility": "hidden"
+            },
+            "projectId": {
+              "visibility": "hidden"
+            },
+            "workRefType": {
+              "visibility": "hidden"
+            },
+            "workRefId": {
+              "visibility": "hidden"
+            },
+            "pricingRuleId": {
+              "visibility": "hidden"
+            },
+            "priceBookId": {
+              "visibility": "hidden"
+            },
+            "pricingSnapshot": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nSubscriptions is where you sell plans that renew. A plan says what it costs,\nhow often it bills and whether it is free, a fixed price or pay what you can.\nA subscription joins a subscriber to a plan and shows where it stands, from\ntrial to active to cancelled. Every time you change a plan's terms, the\nearlier terms are kept as a plan version, so a subscriber who already paid for\na period keeps what they paid for until it renews. Charges show what each\nsubscriber used and what it cost them.\n\nAll amounts are whole numbers of cents, with no decimal point.\n\n## Tasks\n\n### Set up a plan\n\n1. Open the plans and choose **New**.\n2. Type the **{field:SubscriptionPlan.name}** customers will see and a short **{field:SubscriptionPlan.planKey}** such as \"starter\".\n3. Choose **{field:SubscriptionPlan.pricingMode}**: free, a fixed price, or pay what you can. This cannot change once the plan is saved; make a new plan instead.\n4. For a fixed price, enter the **{field:SubscriptionPlan.priceAmount}** in cents and the **{field:SubscriptionPlan.currency}**.\n5. Set how often it bills in **{field:SubscriptionPlan.billingInterval}**.\n6. Set the **{field:SubscriptionPlan.status}** to active when it is ready to sell.\n7. Save.\n\n### Change a plan's price or terms\n\n1. Open the plan and edit the **{field:SubscriptionPlan.priceAmount}**, **{field:SubscriptionPlan.billingInterval}** or **{field:SubscriptionPlan.status}**.\n2. Save. The new terms apply to new subscribers and to existing ones from their next renewal; a period already paid for keeps its old terms.\n\n### Retire a plan\n\n1. Open the plan and set its **{field:SubscriptionPlan.status}** to archived.\n2. Save. No one new can subscribe to it; existing subscribers keep going until they cancel.\n\n### Subscribe someone to a plan\n\n1. Open the subscriptions and choose **New**.\n2. Pick the **{field:TenantSubscription.planId}**.\n3. Enter the day it **{field:TenantSubscription.startedAt}** and, if there is a free trial, when the **{field:TenantSubscription.trialEndsAt}**.\n4. Save. The **{field:TenantSubscription.status}** shows where the subscription stands once it has been paid for.\n\n### See where a subscription stands\n\n1. Open the subscriptions and find the one you want.\n2. The **{field:TenantSubscription.status}** shows whether it is still incomplete, on trial, active, past due, unpaid or cancelled.\n3. **{field:TenantSubscription.currentPeriodStart}** and **{field:TenantSubscription.currentPeriodEnd}** show the period that has been paid for.\n\n### Cancel a subscription\n\n1. Open the subscription.\n2. Tick **{field:TenantSubscription.cancelAtPeriodEnd}** so it runs out when the current period ends instead of renewing.\n3. Save.\n\n### Look up the terms a subscriber was sold\n\nPlan versions are written automatically whenever a plan is saved with changed\nterms; you cannot add or edit them here.\n\n1. Open the plan versions and find the **{field:SubscriptionPlanVersion.planId}** you are interested in.\n2. Each row shows the **{field:SubscriptionPlanVersion.version}** and the date it was **{field:SubscriptionPlanVersion.effectiveFrom}**.\n3. Read the **{field:SubscriptionPlanVersion.priceAmount}**, **{field:SubscriptionPlanVersion.currency}** and **{field:SubscriptionPlanVersion.billingInterval}** that applied under it.\n\n### See what a subscriber was charged\n\nCharges are created by the usage and billing service as usage is recorded;\nyou cannot add or edit them here.\n\n1. Open the charges.\n2. Each row shows **{field:ClientCharge.metricKey}**, **{field:ClientCharge.quantity}** and the **{field:ClientCharge.amount}** in cents.\n3. The **{field:ClientCharge.status}** shows whether the charge is still a draft, approved or adjusted.\n",
+        "fieldRefs": [
+          "ClientCharge.amount",
+          "ClientCharge.metricKey",
+          "ClientCharge.quantity",
+          "ClientCharge.status",
+          "SubscriptionPlan.billingInterval",
+          "SubscriptionPlan.currency",
+          "SubscriptionPlan.name",
+          "SubscriptionPlan.planKey",
+          "SubscriptionPlan.priceAmount",
+          "SubscriptionPlan.pricingMode",
+          "SubscriptionPlan.status",
+          "SubscriptionPlanVersion.billingInterval",
+          "SubscriptionPlanVersion.currency",
+          "SubscriptionPlanVersion.effectiveFrom",
+          "SubscriptionPlanVersion.planId",
+          "SubscriptionPlanVersion.priceAmount",
+          "SubscriptionPlanVersion.version",
+          "TenantSubscription.cancelAtPeriodEnd",
+          "TenantSubscription.currentPeriodEnd",
+          "TenantSubscription.currentPeriodStart",
+          "TenantSubscription.planId",
+          "TenantSubscription.startedAt",
+          "TenantSubscription.status",
+          "TenantSubscription.trialEndsAt"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package does not build for a browser: core migrations (node:crypto, node:os); and its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624, #3626)."
+        ]
+      }
+    }
+  ],
   "browser": {
     "status": "server-only",
     "issues": [