@happyvertical/smrt-subscriptions 0.60.15 → 0.60.16

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-subscriptions",
-  "packageVersion": "0.60.15",
+  "packageVersion": "0.60.16",
   "objects": {
     "@happyvertical/smrt-subscriptions:SubscriptionPlanCollection": {
       "name": "subscriptionplancollection",
@@ -1132,6 +1132,311 @@
       },
       "importPath": "@happyvertical/smrt-subscriptions"
     },
+    "@happyvertical/smrt-subscriptions:BillingCheckoutSession": {
+      "name": "billingcheckoutsession",
+      "className": "BillingCheckoutSession",
+      "qualifiedName": "@happyvertical/smrt-subscriptions:BillingCheckoutSession",
+      "collection": "billingcheckoutsessions",
+      "description": "One Checkout session created by the billing host, recorded when the host creates it and required when the paid session completes, so signed metadata copied onto another integration's session is never…",
+      "filePath": "/home/runner/work/smrt/smrt/packages/subscriptions/src/models/BillingCheckoutSession.ts",
+      "packageName": "@happyvertical/smrt-subscriptions",
+      "fields": {
+        "sessionId": {
+          "type": "text",
+          "required": true,
+          "default": "",
+          "_meta": {
+            "required": true
+          }
+        },
+        "targetTenantId": {
+          "type": "text",
+          "required": false,
+          "default": "",
+          "description": "The tenant the host created the session for.",
+          "_meta": {
+            "description": "The tenant the host created the session for."
+          }
+        },
+        "status": {
+          "type": "text",
+          "required": false,
+          "default": "pending",
+          "enum": [
+            "pending",
+            "completed",
+            "needs_reconciliation",
+            "dismissed"
+          ]
+        },
+        "expiresAt": {
+          "type": "datetime",
+          "required": false
+        },
+        "completedAt": {
+          "type": "datetime",
+          "required": false
+        },
+        "reason": {
+          "type": "text",
+          "required": false,
+          "default": ""
+        },
+        "detail": {
+          "type": "text",
+          "required": false,
+          "default": "{}"
+        }
+      },
+      "methods": {},
+      "decoratorConfig": {
+        "tableName": "_smrt_billing_checkout_sessions",
+        "conflictColumns": [
+          "session_id"
+        ],
+        "api": false,
+        "cli": false,
+        "mcp": false
+      },
+      "extends": "SmrtObject",
+      "exportName": "BillingCheckoutSession",
+      "collectionExportName": "BillingCheckoutSessionCollection",
+      "validationRules": [
+        {
+          "field": "sessionId",
+          "rule": "required",
+          "fieldType": "text"
+        }
+      ],
+      "schema": {
+        "tableName": "_smrt_billing_checkout_sessions",
+        "ddl": "CREATE TABLE IF NOT EXISTS \"_smrt_billing_checkout_sessions\" (\n  \"_sync_origin_device_id\" TEXT,\n  \"_sync_revision\" INTEGER,\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"session_id\" TEXT NOT NULL DEFAULT '',\n  \"target_tenant_id\" TEXT DEFAULT '',\n  \"status\" TEXT DEFAULT 'pending',\n  \"expires_at\" TIMESTAMP,\n  \"completed_at\" TIMESTAMP,\n  \"reason\" TEXT DEFAULT '',\n  \"detail\" TEXT DEFAULT '{}'\n);",
+        "columns": {
+          "_sync_origin_device_id": {
+            "type": "TEXT"
+          },
+          "_sync_revision": {
+            "type": "INTEGER"
+          },
+          "id": {
+            "type": "UUID",
+            "primaryKey": true,
+            "referenceKind": "id",
+            "notNull": true
+          },
+          "slug": {
+            "type": "TEXT",
+            "notNull": true
+          },
+          "context": {
+            "type": "TEXT",
+            "notNull": true,
+            "default": ""
+          },
+          "created_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "updated_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "session_id": {
+            "type": "TEXT",
+            "notNull": true,
+            "unique": false,
+            "default": ""
+          },
+          "target_tenant_id": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": ""
+          },
+          "status": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": "pending"
+          },
+          "expires_at": {
+            "type": "TIMESTAMP",
+            "notNull": false,
+            "unique": false
+          },
+          "completed_at": {
+            "type": "TIMESTAMP",
+            "notNull": false,
+            "unique": false
+          },
+          "reason": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": ""
+          },
+          "detail": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": "{}"
+          }
+        },
+        "indexes": [
+          {
+            "name": "_smrt_billing_checkout_sessions_session_id_idx",
+            "columns": [
+              "session_id"
+            ],
+            "unique": true
+          },
+          {
+            "name": "_smrt_billing_checkout_sessions_slug_context_idx",
+            "columns": [
+              "slug",
+              "context"
+            ]
+          },
+          {
+            "name": "_smrt_billing_checkout_sessions_created_at_idx",
+            "columns": [
+              "created_at"
+            ]
+          }
+        ],
+        "version": "c1924881"
+      },
+      "importPath": "@happyvertical/smrt-subscriptions"
+    },
+    "@happyvertical/smrt-subscriptions:BillingCheckoutSessionCollection": {
+      "name": "billingcheckoutsessioncollection",
+      "className": "BillingCheckoutSessionCollection",
+      "qualifiedName": "@happyvertical/smrt-subscriptions:BillingCheckoutSessionCollection",
+      "collection": "billingcheckoutsessions",
+      "filePath": "/home/runner/work/smrt/smrt/packages/subscriptions/src/models/BillingCheckoutSession.ts",
+      "packageName": "@happyvertical/smrt-subscriptions",
+      "fields": {},
+      "methods": {},
+      "decoratorConfig": {
+        "tableName": "_smrt_billing_checkout_sessions",
+        "api": false,
+        "mcp": false,
+        "cli": false
+      },
+      "extends": "SmrtCollection",
+      "extendsTypeArg": "BillingCheckoutSession",
+      "exportName": "BillingCheckoutSessionCollection",
+      "collectionExportName": "BillingCheckoutSessionCollectionCollection",
+      "collectionOf": "@happyvertical/smrt-subscriptions:BillingCheckoutSession",
+      "inheritedExposure": [
+        "api",
+        "mcp",
+        "cli"
+      ],
+      "schema": {
+        "tableName": "_smrt_billing_checkout_sessions",
+        "ddl": "CREATE TABLE IF NOT EXISTS \"_smrt_billing_checkout_sessions\" (\n  \"_sync_origin_device_id\" TEXT,\n  \"_sync_revision\" INTEGER,\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"session_id\" TEXT NOT NULL DEFAULT '',\n  \"target_tenant_id\" TEXT DEFAULT '',\n  \"status\" TEXT DEFAULT 'pending',\n  \"expires_at\" TIMESTAMP,\n  \"completed_at\" TIMESTAMP,\n  \"reason\" TEXT DEFAULT '',\n  \"detail\" TEXT DEFAULT '{}'\n);",
+        "columns": {
+          "_sync_origin_device_id": {
+            "type": "TEXT"
+          },
+          "_sync_revision": {
+            "type": "INTEGER"
+          },
+          "id": {
+            "type": "UUID",
+            "primaryKey": true,
+            "referenceKind": "id",
+            "notNull": true
+          },
+          "slug": {
+            "type": "TEXT",
+            "notNull": true
+          },
+          "context": {
+            "type": "TEXT",
+            "notNull": true,
+            "default": ""
+          },
+          "created_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "updated_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "session_id": {
+            "type": "TEXT",
+            "notNull": true,
+            "unique": false,
+            "default": ""
+          },
+          "target_tenant_id": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": ""
+          },
+          "status": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": "pending"
+          },
+          "expires_at": {
+            "type": "TIMESTAMP",
+            "notNull": false,
+            "unique": false
+          },
+          "completed_at": {
+            "type": "TIMESTAMP",
+            "notNull": false,
+            "unique": false
+          },
+          "reason": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": ""
+          },
+          "detail": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false,
+            "default": "{}"
+          }
+        },
+        "indexes": [
+          {
+            "name": "_smrt_billing_checkout_sessions_session_id_idx",
+            "columns": [
+              "session_id"
+            ],
+            "unique": true
+          },
+          {
+            "name": "_smrt_billing_checkout_sessions_slug_context_idx",
+            "columns": [
+              "slug",
+              "context"
+            ]
+          },
+          {
+            "name": "_smrt_billing_checkout_sessions_created_at_idx",
+            "columns": [
+              "created_at"
+            ]
+          }
+        ],
+        "version": "c1924881"
+      },
+      "importPath": "@happyvertical/smrt-subscriptions"
+    },
     "@happyvertical/smrt-subscriptions:SubscriptionPlan": {
       "name": "subscriptionplan",
       "className": "SubscriptionPlan",
@@ -6894,7 +7199,7 @@
       "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)."
+          "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-profiles, @happyvertical/smrt-tenancy, @happyvertical/smrt-users, which do not build for a browser (#3617, #3624, #3626)."
         ]
       }
     }
@@ -6902,17 +7207,21 @@
   "smrtDependencies": [
     "@happyvertical/smrt-core",
     "@happyvertical/smrt-features",
-    "@happyvertical/smrt-tenancy"
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-users"
   ],
   "browser": {
     "status": "server-only",
     "issues": [
+      "#3617",
       "#3624",
       "#3626"
     ],
     "reason": "core migrations (node:crypto, node:os)",
     "via": [
-      "@happyvertical/smrt-tenancy"
+      "@happyvertical/smrt-profiles",
+      "@happyvertical/smrt-tenancy",
+      "@happyvertical/smrt-users"
     ]
   },
   "stampsConstructors": true

package/dist/models/BillingCheckoutSession.d.ts

@@ -0,0 +1,39 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * Where a Checkout session the billing host created stands (#4814).
+ *
+ * - `pending`: created by the host, not yet completed.
+ * - `completed`: the paid session was linked to its tenant (single use).
+ * - `needs_reconciliation`: a paid session whose record was missing, expired
+ *   or did not match. It is not linked; an operator links it on purpose with
+ *   `BillingHost.reconcileCheckout()`.
+ */
+export type BillingCheckoutSessionStatus = 'pending' | 'completed' | 'needs_reconciliation' | 'dismissed';
+/**
+ * One Checkout session created by the billing host, recorded when the host
+ * creates it and required when the paid session completes, so signed
+ * metadata copied onto another integration's session is never trusted.
+ * `sessionId` is the provider's unguessable, unique id and doubles as the
+ * single-use nonce.
+ *
+ * A system table managed through `createBillingHost()`, like
+ * `_smrt_price_book_assignments`; it has no generated API surface. It is a
+ * root export because the published manifest advertises it. `tenantId` is the
+ * tenant the host created the session for (`''` on a row opened for a session
+ * the host never recorded).
+ */
+export declare class BillingCheckoutSession extends SmrtObject {
+    sessionId: string;
+    targetTenantId: string;
+    status: BillingCheckoutSessionStatus;
+    expiresAt: Date;
+    completedAt: Date | null;
+    /** Why the row needs reconciliation (a code, never provider text). */
+    reason: string;
+    /** JSON ids needed to reconcile: event, subscription, customer, plan. */
+    detail: string;
+}
+export declare class BillingCheckoutSessionCollection extends SmrtCollection<BillingCheckoutSession> {
+    static readonly _itemClass: typeof BillingCheckoutSession;
+}
+//# sourceMappingURL=BillingCheckoutSession.d.ts.map

package/dist/models/BillingCheckoutSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BillingCheckoutSession.d.ts","sourceRoot":"","sources":["../../src/models/BillingCheckoutSession.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACd,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,MAAM,4BAA4B,GACpC,SAAS,GACT,WAAW,GACX,sBAAsB,GACtB,WAAW,CAAC;AAEhB;;;;;;;;;;;;GAYG;AACH,qBAOa,sBAAuB,SAAQ,UAAU;IAEpD,SAAS,EAAE,MAAM,CAAM;IAEvB,cAAc,EAAE,MAAM,CAAM;IAC5B,MAAM,EAAE,4BAA4B,CAAa;IACjD,SAAS,EAAE,IAAI,CAAe;IAC9B,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAChC,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAM;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAQ;CACvB;AAED,qBAAa,gCAAiC,SAAQ,cAAc,CAAC,sBAAsB,CAAC;IAC1F,MAAM,CAAC,QAAQ,CAAC,UAAU,gCAA0B;CACrD"}

package/dist/models/index.d.ts

@@ -1,3 +1,4 @@
+export { BillingCheckoutSession } from './BillingCheckoutSession.js';
 export type { PricingStrategy, SpendingBasis, SpendingPeriod, SpendingPolicyBehavior, } from './commercial.js';
 export { BillingAdjustment, BillingAdjustmentCollection, ClientCharge, ClientChargeCollection, PricingRule, PricingRuleCollection, SpendingPolicy, SpendingPolicyCollection, } from './commercial.js';
 export type { PriceBookKind } from './reseller.js';

package/dist/models/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,aAAa,EACb,cAAc,EACd,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,YAAY,EACZ,sBAAsB,EACtB,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,SAAS,EACT,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EACV,eAAe,EACf,aAAa,EACb,cAAc,EACd,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,YAAY,EACZ,sBAAsB,EACtB,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,SAAS,EACT,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/recipes.d.ts

@@ -29,7 +29,7 @@ export declare class SubscriptionPlansRecipe extends SmrtRecipe {
         icon: string;
         description: string;
     };
-    static models: (typeof SubscriptionPlanVersion | typeof TenantSubscription | typeof SubscriptionPlan | typeof ClientCharge)[];
+    static models: (typeof SubscriptionPlan | typeof SubscriptionPlanVersion | typeof TenantSubscription | typeof ClientCharge)[];
     static nav: ({
         label: string;
         model: typeof SubscriptionPlan;

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-subscriptions",
-  "packageVersion": "0.60.15",
+  "packageVersion": "0.60.16",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "f4816979dc2afcb8355251a0fc02a249c9098e0a8b5224d53066244daabfb538",
-    "packageJson": "59ca645f3cb564affced4b5417316c97ffb8cae0c561edf79239c7d11fafef44",
-    "agents": "51c6ab853fadd46068e2146e60313a0818cb1e10fdc28abb97fc00a5173e1bbb"
+    "manifest": "d0344a095641eda1066db194207f42badf47b28e0caf1fcc03afc73172b003eb",
+    "packageJson": "223e5c265728c912465daa447faf2c245561cdd69ba46abceca53596ec82a694",
+    "agents": "920c91705242b95baed544fa2b33223935353a247a9b9946c5776a315525e642"
   },
   "exports": [
     ".",
@@ -21,7 +21,9 @@
     "@happyvertical/smrt-core": "workspace:*",
     "@happyvertical/smrt-tenancy": "workspace:*",
     "@happyvertical/smrt-ui": "workspace:*",
+    "@happyvertical/smrt-users": "workspace:*",
     "@happyvertical/sql": "catalog:",
+    "@happyvertical/accounting": "catalog:",
     "@happyvertical/smrt-features": "workspace:*",
     "@happyvertical/smrt-vitest": "workspace:*",
     "@sveltejs/package": "^2.5.8",
@@ -37,6 +39,7 @@
     "@happyvertical/smrt-features",
     "@happyvertical/smrt-tenancy",
     "@happyvertical/smrt-ui",
+    "@happyvertical/smrt-users",
     "@happyvertical/smrt-vitest"
   ],
   "sdkDependencies": [
@@ -469,6 +472,93 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "BillingCheckoutSession",
+      "qualifiedName": "@happyvertical/smrt-subscriptions:BillingCheckoutSession",
+      "collection": "billingcheckoutsessions",
+      "description": "One Checkout session created by the billing host, recorded when the host creates it and required when the paid session completes, so signed metadata copied onto another integration's session is never…",
+      "tableName": "_smrt_billing_checkout_sessions",
+      "packageName": "@happyvertical/smrt-subscriptions",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "sessionId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "targetTenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "The tenant the host created the session for."
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "pending"
+        },
+        {
+          "name": "expiresAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "completedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "reason",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "detail",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "{}"
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "conflictColumns": [
+        "session_id"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "BillingCheckoutSessionCollection",
+      "qualifiedName": "@happyvertical/smrt-subscriptions:BillingCheckoutSessionCollection",
+      "collection": "billingcheckoutsessions",
+      "tableName": "_smrt_billing_checkout_sessions",
+      "packageName": "@happyvertical/smrt-subscriptions",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "SubscriptionPlan",
       "qualifiedName": "@happyvertical/smrt-subscriptions:SubscriptionPlan",
@@ -4230,9 +4320,9 @@
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 88
+    "uuidColumns": 90
   },
-  "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## Hosted AI spend caps (#4760)\n\n`src/services/hosted-ai-spend.ts`. Plans cap platform-paid (`source:\nhosted`) inference with ordinary `PlanThreshold`s on two reserved keys, so\nwindow, amount and enforcement come from the plan (pinned version included):\n`AI_HOSTED_SPEND_METRIC` (`ai.hosted.spend_micros`, the tenant) and\n`AI_HOSTED_USER_SPEND_METRIC` (`ai.hosted.user_spend_micros`, each user).\n\n- `limit` is **integer micro-dollars** (1 USD = 1,000,000; the money rule at\n  per-call precision). `block` blocks at or over the cap, `warn` warns,\n  `observe` never affects a call; `warningRatio` (default 0.8) warns early;\n  a 0 cap blocks every hosted call. A malformed hosted cap (fractional or\n  negative limit, unknown window/enforcement) throws\n  `HostedAiSpendPolicyError` (the gate fails closed); it never reads as \"no\n  cap\". `resolvePlanThresholds()` returns thresholds unfiltered for this\n  reason (the models' `getThresholds()` drop invalid entries) and throws on\n  non-array JSON.\n- Spend: `createHostedAiSpendReader(db)` sums `_smrt_ai_usage.estimated_cost`\n  (USD, rounded to micro-dollars) by `tenant_id` and `created_at` in the\n  cap's window for rows whose `tags` hold `\"source\":\"hosted\"` (and\n  `\"userId\":\"<id>\"` for the per-user cap), as exact, case-sensitive JSON\n  fragments (`hostedAiTagFragment()`; `strpos` on the PostgreSQL dialect,\n  `instr` elsewhere, never `LIKE`, which folds ASCII case on SQLite and\n  would merge `Alice` and `alice`); errors only over-count.\n  `operation: 'blocked'` rows and external-agent measurements never count;\n  uncosted rows add nothing (give hosted models a cost rate). The `userId`\n  tag exists only while the hosted gate's ambient-user resolver is\n  registered.\n- `resetsAt`: the calendar window's end; for a blocked `rolling` cap (30\n  days), `HostedAiSpendReader.liftsAt()`: one window-function query (newest\n  first running `SUM(estimated_cost)`, rounded as `summarize()` rounds)\n  returns the row whose expiry first brings the total below the cap, plus\n  30 days (null for a 0 cap). A blocked decision names the blocking cap that\n  lifts last.\n- `HostedAiSpendEvaluator` (`create({ db })`): plan thresholds via\n  `SubscriptionResolver.resolvePlanThresholds()` (entitled terms, no usage\n  meters; memoized per tenant for `termsTtlMs`, 30 s, failures evicted,\n  `invalidate()`), spend read fresh per call; per-user caps only with a\n  user. Errors propagate. smrt-inference's `./gate` consumes it.\n- `resolveEntitlements()` / the tenant usage meter report these keys with\n  quantity 0: only the evaluator meters them. The meter's AI summary (and so\n  `ai.requests`) skips `operation: 'blocked'` rows. `SpendingPolicy` rows stay the\n  billed-charge (cents) policy; hosted AI caps are plan terms because the\n  issue's window and amount come from the plan.\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- **Feature grants as flags (#4761).** `SubscriptionFeatureSource` implements\n  `smrt-features`' `FeatureGrantSource` structurally (no dependency either\n  way). Build one per request (`SubscriptionFeatureSource.create(options)` or\n  `new SubscriptionFeatureSource({ resolver })`; it memoizes grants per\n  tenant) and pass it as `grantSource`, or register an app-wide one built with\n  `memoize: false` through `registerSubscriptionFeatureSource()`, which writes\n  the features slot key `FEATURE_GRANT_SOURCE_SLOT_KEY`. It reads\n  `SubscriptionResolver.resolveFeatureGrants()`, which shares the\n  version-pinning and entitlement rules of `resolveEntitlements()` but never\n  evaluates thresholds, so a flag check reads no usage meters. Missing\n  subscription tables (`isMissingSubscriptionTableError`) and no entitled\n  subscription report no grants silently; every other error propagates.\n  `findGrantingPlan()` names the first active plan by `sortOrder` visible in\n  the current context.\n- **Entitlement change hook (#4759).** `src/services/entitlement-changes.ts`.\n  The host wraps its billing-webhook write in\n  `trackEntitlementChange({ tenantId, resolver }, apply)`: it snapshots\n  `resolveFeatureGrants()` (keys plus grant `metadata`, no usage reads)\n  before and after, diffs `gained` / `lost` / `changed` (metadata, e.g. a\n  plan budget) and calls listeners registered with\n  `registerEntitlementChangeListener()` (a `Symbol.for` slot) or passed in.\n  Listeners run after `apply`; their failures are returned in `failures`,\n  never thrown, and never undo the write, so listeners must be idempotent.\n  An `apply` error propagates and notifies nobody. A redelivered webhook\n  diffs to no change, so a lost reaction is repaired by the consumer's\n  reconcile entry point (hosted inference: `createHostedInferenceReconciler()`\n  with `snapshotEntitlements()`), run on redelivery or a schedule. Listeners satisfy the\n  structural type (smrt-inference's hosted listener), so this package\n  depends on none of them.\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## Hosted AI spend caps (#4760)\n\n`src/services/hosted-ai-spend.ts`. Plans cap platform-paid (`source:\nhosted`) inference with ordinary `PlanThreshold`s on two reserved keys, so\nwindow, amount and enforcement come from the plan (pinned version included):\n`AI_HOSTED_SPEND_METRIC` (`ai.hosted.spend_micros`, the tenant) and\n`AI_HOSTED_USER_SPEND_METRIC` (`ai.hosted.user_spend_micros`, each user).\n\n- `limit` is **integer micro-dollars** (1 USD = 1,000,000; the money rule at\n  per-call precision). `block` blocks at or over the cap, `warn` warns,\n  `observe` never affects a call; `warningRatio` (default 0.8) warns early;\n  a 0 cap blocks every hosted call. A malformed hosted cap (fractional or\n  negative limit, unknown window/enforcement) throws\n  `HostedAiSpendPolicyError` (the gate fails closed); it never reads as \"no\n  cap\". `resolvePlanThresholds()` returns thresholds unfiltered for this\n  reason (the models' `getThresholds()` drop invalid entries) and throws on\n  non-array JSON.\n- Spend: `createHostedAiSpendReader(db)` sums `_smrt_ai_usage.estimated_cost`\n  (USD, rounded to micro-dollars) by `tenant_id` and `created_at` in the\n  cap's window for rows whose `tags` hold `\"source\":\"hosted\"` (and\n  `\"userId\":\"<id>\"` for the per-user cap), as exact, case-sensitive JSON\n  fragments (`hostedAiTagFragment()`; `strpos` on the PostgreSQL dialect,\n  `instr` elsewhere, never `LIKE`, which folds ASCII case on SQLite and\n  would merge `Alice` and `alice`); errors only over-count.\n  `operation: 'blocked'` rows and external-agent measurements never count;\n  uncosted rows add nothing (give hosted models a cost rate). The `userId`\n  tag exists only while the hosted gate's ambient-user resolver is\n  registered.\n- `resetsAt`: the calendar window's end; for a blocked `rolling` cap (30\n  days), `HostedAiSpendReader.liftsAt()`: one window-function query (newest\n  first running `SUM(estimated_cost)`, rounded as `summarize()` rounds)\n  returns the row whose expiry first brings the total below the cap, plus\n  30 days (null for a 0 cap). A blocked decision names the blocking cap that\n  lifts last.\n- `HostedAiSpendEvaluator` (`create({ db })`): plan thresholds via\n  `SubscriptionResolver.resolvePlanThresholds()` (entitled terms, no usage\n  meters; memoized per tenant for `termsTtlMs`, 30 s, failures evicted,\n  `invalidate()`), spend read fresh per call; per-user caps only with a\n  user. Errors propagate. smrt-inference's `./gate` consumes it.\n- `resolveEntitlements()` / the tenant usage meter report these keys with\n  quantity 0: only the evaluator meters them. The meter's AI summary (and so\n  `ai.requests`) skips `operation: 'blocked'` rows. `SpendingPolicy` rows stay the\n  billed-charge (cents) policy; hosted AI caps are plan terms because the\n  issue's window and amount come from the plan.\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## Billing host glue (#4786)\n\n`src/billing/` is the reusable Stripe checkout, signed idempotent webhook and\nportal wiring (`createBillingHost()`, `readBillingEnv()`); the recipe and\nenvironment names are in the README. Invariants:\n\n- **No direct Stripe calls.** The provider is the structural\n  `BillingProviderPort`; `StripeAccountingProvider` from\n  `@happyvertical/accounting` satisfies it (a test pins that). A missing SDK\n  capability is fixed in the SDK first. `@happyvertical/accounting` is a\n  devDependency only (tests run the real provider over a fake `fetch`).\n- **Webhook order is load-bearing:** size cap, signature header, own timestamp\n  tolerance, SDK `verify` on the raw body, parse, handled-type filter,\n  completed-claim pre-check, then (checkout only) the outside-transaction\n  provider read-back, then `runOnce` claiming the event id *and* applying it.\n  All DB access inside that transaction must use the `tx` handle; a read on the\n  base handle deadlocks single-connection SQLite. Never claim before applying.\n- **Trust comes from our own state.** Checkout metadata is HMAC-signed\n  (`smrt_sig`, `signing.ts`) and an unsigned or foreign-signed session never\n  links a tenant or plan.\n- **Checkout is bound to a recorded session (#4814)**, `checkout-sessions.ts`\n  and `models/BillingCheckoutSession.ts` (`_smrt_billing_checkout_sessions`,\n  no API surface; a root export because the manifest advertises it).\n  `createCheckout` records the session id\n  before returning the URL and signs `smrt_exp`; the completion (inside the\n  `runOnce` transaction, after the PostgreSQL `checkout:<id>` lock) checks, in\n  order: record exists, status is not `completed` / `needs_reconciliation`\n  (no-op `ignored`), record tenant equals the signed tenant, `smrt_exp` is\n  well-formed, event time is not after the signed or recorded expiry. A\n  missing, mismatched or expired record never links and never drops: the row\n  becomes `needs_reconciliation` (outcome `needs_reconciliation`, error log).\n  Only `applied` marks a record `completed`. `reconcileCheckout()` (link) and\n  `dismissCheckout()` (terminal `dismissed`, for a payment that is not the\n  tenant's) are the only ways out and are operator-only; reconcile never skips\n  the apply-time conflict checks. The list shows `customerId`,\n  `targetTenantId` and `claimedTenantHasOwnSession`, is paged, and has a count.\n  The expiry is deterministic per idempotency window so a repeated click sends\n  identical provider parameters. Change the table shape only with owner\n  approval. A provider subscription or customer id links to one\n  tenant; a conflicting event is ignored with a reason code, not merged.\n  Verification accepts the signing secret plus `metadataVerificationSecrets`\n  (rotation); a purpose-matching session that fails them logs at error.\n  A price the host cannot map that differs from the recorded one is held\n  (`incomplete`, plan and recorded price kept, `metadata.stripe.held` set so\n  checkout still refuses a second subscription) with an error log, never\n  carried over onto the previous plan.\n  Ignore (2xx, logged) for security refusals; fail (5xx) for configuration or\n  database faults so the provider retries.\n- **Only operator plans are sold by default** (`tenantPlans: 'deny'`); price\n  resolution never lets a tenant-owned plan outrank a global one. Checkout\n  metadata also signs the price and known customer, and the webhook refuses a\n  session whose read-back subscription differs. PostgreSQL events lock the\n  subscription and tenant (advisory, sorted) and re-read before deciding.\n- **Order state lives on the row** (`metadata.stripe.lastEventAt`, `terminal`);\n  a checkout read-back stamps `max(eventCreated, readAt)` so later-delivered\n  older events cannot rewind it. Cancellation caps `currentPeriodEnd` at now.\n- **Plan changes** from the provider use `replacePlanVersion({ policy:\n  'authorized', reason: 'stripe:<eventId>' })`; the provider billed the change,\n  so a mid-period downgrade is honoured and audited. Do not relax the pinning\n  rules for any other caller.\n- **No secrets out.** Responses use fixed messages; logs get ids and reason\n  codes only, errors pass through `safeErrorMessage()`. `readBillingEnv` keeps\n  secrets non-enumerable. Add a named test per new threat in\n  `__tests__/billing-host.test.ts`.\n\n## Vault account restart and supersede (#4841)\n\n`src/vault-account/`. `supersedeVaultAccount`, `unsupersedeVaultAccount` and\n`provisionRestartAccount` take injected ports (`VaultRelayAdminPort`,\n`VaultAccountDirectory`, an audit sink); no HTTP server or relay is needed.\nOrder is load-bearing: owner of the tenant and of both accounts (`not_owner`),\nthen `requireRecentAuthentication` from `smrt-users/step-up`\n(`step_up_required`, default 300 s), then the `authorized` audit record, then\nexactly one relay call, then the outcome record. Refusals are audited and never\nreach the relay; a member never learns about the step-up. Audit entries carry\nids and codes only (no session id, key, token or message text). Import only the\n`@happyvertical/smrt-users/step-up` subpath, never the package root.\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- **Feature grants as flags (#4761).** `SubscriptionFeatureSource` implements\n  `smrt-features`' `FeatureGrantSource` structurally (no dependency either\n  way). Build one per request (`SubscriptionFeatureSource.create(options)` or\n  `new SubscriptionFeatureSource({ resolver })`; it memoizes grants per\n  tenant) and pass it as `grantSource`, or register an app-wide one built with\n  `memoize: false` through `registerSubscriptionFeatureSource()`, which writes\n  the features slot key `FEATURE_GRANT_SOURCE_SLOT_KEY`. It reads\n  `SubscriptionResolver.resolveFeatureGrants()`, which shares the\n  version-pinning and entitlement rules of `resolveEntitlements()` but never\n  evaluates thresholds, so a flag check reads no usage meters. Missing\n  subscription tables (`isMissingSubscriptionTableError`) and no entitled\n  subscription report no grants silently; every other error propagates.\n  `findGrantingPlan()` names the first active plan by `sortOrder` visible in\n  the current context.\n- **Entitlement change hook (#4759).** `src/services/entitlement-changes.ts`.\n  The host wraps its billing-webhook write in\n  `trackEntitlementChange({ tenantId, resolver }, apply)`: it snapshots\n  `resolveFeatureGrants()` (keys plus grant `metadata`, no usage reads)\n  before and after, diffs `gained` / `lost` / `changed` (metadata, e.g. a\n  plan budget) and calls listeners registered with\n  `registerEntitlementChangeListener()` (a `Symbol.for` slot) or passed in.\n  Listeners run after `apply`; their failures are returned in `failures`,\n  never thrown, and never undo the write, so listeners must be idempotent.\n  An `apply` error propagates and notifies nobody. A redelivered webhook\n  diffs to no change, so a lost reaction is repaired by the consumer's\n  reconcile entry point (hosted inference: `createHostedInferenceReconciler()`\n  with `snapshotEntitlements()`), run on redelivery or a schedule. Listeners satisfy the\n  structural type (smrt-inference's hosted listener), so this package\n  depends on none of them.\n",
   "recipes": [
     {
       "id": "subscriptions.plans",
@@ -4601,7 +4691,7 @@
       "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)."
+          "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-profiles, @happyvertical/smrt-tenancy, @happyvertical/smrt-users, which do not build for a browser (#3617, #3624, #3626)."
         ]
       }
     }
@@ -4609,12 +4699,15 @@
   "browser": {
     "status": "server-only",
     "issues": [
+      "#3617",
       "#3624",
       "#3626"
     ],
     "reason": "core migrations (node:crypto, node:os)",
     "via": [
-      "@happyvertical/smrt-tenancy"
+      "@happyvertical/smrt-profiles",
+      "@happyvertical/smrt-tenancy",
+      "@happyvertical/smrt-users"
     ]
   }
 }