@happyvertical/smrt-subscriptions 0.57.9 → 0.57.10

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.9",
+  "packageVersion": "0.57.10",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "07269dcbdf20f93876f33fd972e51c473dee5151079c56316dae799d612b980e",
-    "packageJson": "d669da9c36c5e5105d8973dc8b8e9736bb56d6f37d2b9f70054a247e1a62332e",
-    "agents": "89ab9b5f7047d2f7f316a4bbbb1eef225f3fa8e85f21cb9a699ec3ce18bdb9cd"
+    "manifest": "230888d57f42ed4f6743c05d2272779cdcf47599eedab5b4a2e52aa7b5b8bbfa",
+    "packageJson": "f23eb15869858c996cfce6d5a3338844f9e434141c9bd5688a83d73f7ee3a6f2",
+    "agents": "8d03287e49f241cfe3f1dac0a3bd32ffc51d67709c1e2af93e0368cd0cadaf02"
   },
   "exports": [
     ".",
@@ -162,6 +162,95 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "SubscriptionPlanVersionCollection",
+      "qualifiedName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersionCollection",
+      "collection": "subscriptionplanversions",
+      "description": "Effective-dated plan versions (#4032).",
+      "tableName": "_smrt_subscription_plan_versions",
+      "packageName": "@happyvertical/smrt-subscriptions",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findInForce",
+        "findLatest",
+        "findVisibleById",
+        "listForPlan"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findInForce",
+          "async": true,
+          "params": [
+            "planId: string",
+            "at: Date"
+          ],
+          "returns": "Promise<SubscriptionPlanVersion | null>"
+        },
+        {
+          "name": "findLatest",
+          "async": true,
+          "params": [
+            "planId: string",
+            "tenantId?: string | null"
+          ],
+          "returns": "Promise<SubscriptionPlanVersion | null>"
+        },
+        {
+          "name": "findVisibleById",
+          "async": true,
+          "params": [
+            "id: string"
+          ],
+          "returns": "Promise<SubscriptionPlanVersion | null>"
+        },
+        {
+          "name": "listForPlan",
+          "async": true,
+          "params": [
+            "planId: string"
+          ],
+          "returns": "Promise<SubscriptionPlanVersion[]>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "findInForce",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersionCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "findLatest",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersionCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "findVisibleById",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersionCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "listForPlan",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersionCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "TenantSubscriptionCollection",
       "qualifiedName": "@happyvertical/smrt-subscriptions:TenantSubscriptionCollection",
@@ -527,8 +616,12 @@
         "getFeatureGrants",
         "getFeatureKeys",
         "getMetadata",
+        "getTerms",
         "getThresholds",
+        "getVersionInForce",
         "isActive",
+        "publishTerms",
+        "save",
         "setFeatureGrants",
         "setMetadata",
         "setThresholds"
@@ -546,14 +639,42 @@
           "name": "getMetadata",
           "returns": "JsonObject"
         },
+        {
+          "name": "getTerms",
+          "returns": "PlanTerms"
+        },
         {
           "name": "getThresholds",
           "returns": "PlanThreshold[]"
         },
+        {
+          "name": "getVersionInForce",
+          "async": true,
+          "params": [
+            "at?: any"
+          ],
+          "returns": "Promise<SubscriptionPlanVersion | null>"
+        },
         {
           "name": "isActive",
           "returns": "boolean"
         },
+        {
+          "name": "publishTerms",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<SubscriptionPlanVersion>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        },
         {
           "name": "setFeatureGrants",
           "params": [
@@ -654,6 +775,24 @@
           "operation": "isActive",
           "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
         },
+        {
+          "kind": "cli",
+          "name": "subscriptionplan_getTerms",
+          "operation": "getTerms",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+        },
+        {
+          "kind": "cli",
+          "name": "subscriptionplan_publishTerms",
+          "operation": "publishTerms",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+        },
+        {
+          "kind": "cli",
+          "name": "subscriptionplan_getVersionInForce",
+          "operation": "getVersionInForce",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+        },
         {
           "kind": "cli",
           "name": "subscriptionplan_getFeatureGrants",
@@ -731,6 +870,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
         },
+        {
+          "kind": "api",
+          "operation": "getTerms",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+        },
         {
           "kind": "api",
           "operation": "getThresholds",
@@ -738,6 +884,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
         },
+        {
+          "kind": "api",
+          "operation": "getVersionInForce",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+        },
         {
           "kind": "api",
           "operation": "isActive",
@@ -745,6 +898,20 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
         },
+        {
+          "kind": "api",
+          "operation": "publishTerms",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+        },
         {
           "kind": "api",
           "operation": "setFeatureGrants",
@@ -773,6 +940,253 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "SubscriptionPlanVersion",
+      "qualifiedName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion",
+      "displayLabelField": "name",
+      "collection": "subscriptionplanversions",
+      "description": "An immutable, effective-dated snapshot of a plan's terms (#4032).",
+      "tableName": "_smrt_subscription_plan_versions",
+      "packageName": "@happyvertical/smrt-subscriptions",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "planId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "SubscriptionPlan",
+          "columnType": "UUID"
+        },
+        {
+          "name": "planKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "version",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "effectiveFrom",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "active"
+        },
+        {
+          "name": "priceAmount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "currency",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "USD"
+        },
+        {
+          "name": "billingInterval",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "month"
+        },
+        {
+          "name": "pricingMode",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "fixed"
+        },
+        {
+          "name": "minimumAmount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "suggestedAmount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "features",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "[]"
+        },
+        {
+          "name": "thresholds",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "[]"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "planId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "SubscriptionPlan",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "getFeatureGrants",
+        "getFeatureKeys",
+        "getTerms",
+        "getThresholds",
+        "isActive"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getFeatureGrants",
+          "returns": "PlanFeatureGrant[]"
+        },
+        {
+          "name": "getFeatureKeys",
+          "returns": "string[]"
+        },
+        {
+          "name": "getTerms",
+          "returns": "PlanTerms"
+        },
+        {
+          "name": "getThresholds",
+          "returns": "PlanThreshold[]"
+        },
+        {
+          "name": "isActive",
+          "returns": "boolean"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "plan_id",
+        "version"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "subscriptionplanversions.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion",
+          "path": "/subscriptionplanversions",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "subscriptionplanversions.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion",
+          "path": "/subscriptionplanversions/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "subscriptionplanversion_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+        },
+        {
+          "kind": "cli",
+          "name": "subscriptionplanversion_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+        },
+        {
+          "kind": "mcp",
+          "name": "subscriptionplanversion_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+        },
+        {
+          "kind": "mcp",
+          "name": "subscriptionplanversion_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getFeatureGrants",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+        },
+        {
+          "kind": "api",
+          "operation": "getFeatureKeys",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+        },
+        {
+          "kind": "api",
+          "operation": "getTerms",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+        },
+        {
+          "kind": "api",
+          "operation": "getThresholds",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+        },
+        {
+          "kind": "api",
+          "operation": "isActive",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "TenantSubscription",
       "qualifiedName": "@happyvertical/smrt-subscriptions:TenantSubscription",
@@ -858,6 +1272,39 @@
           "required": false,
           "columnType": "INTEGER"
         },
+        {
+          "name": "planVersionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "SubscriptionPlanVersion",
+          "columnType": "UUID"
+        },
+        {
+          "name": "planVersionPinnedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "planVersionPinReason",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "planVersionPinNote",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "retainsPaidPeriod",
+          "type": "boolean",
+          "required": false,
+          "columnType": "BOOLEAN",
+          "default": false
+        },
         {
           "name": "externalProvider",
           "type": "text",
@@ -900,12 +1347,20 @@
           "required": false,
           "related": "SubscriptionPlan",
           "columnType": "UUID"
+        },
+        {
+          "name": "planVersionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "SubscriptionPlanVersion",
+          "columnType": "UUID"
         }
       ],
       "methods": [
         "getMetadata",
         "getSubscriber",
         "isEntitled",
+        "replacePlanVersion",
         "setMetadata"
       ],
       "methodSignatures": [
@@ -924,6 +1379,14 @@
           ],
           "returns": "boolean"
         },
+        {
+          "name": "replacePlanVersion",
+          "async": true,
+          "params": [
+            "options: any"
+          ],
+          "returns": "Promise<this>"
+        },
         {
           "name": "setMetadata",
           "params": [
@@ -1005,6 +1468,12 @@
           "operation": "delete",
           "objectName": "@happyvertical/smrt-subscriptions:TenantSubscription"
         },
+        {
+          "kind": "cli",
+          "name": "tenantsubscription_replacePlanVersion",
+          "operation": "replacePlanVersion",
+          "objectName": "@happyvertical/smrt-subscriptions:TenantSubscription"
+        },
         {
           "kind": "cli",
           "name": "tenantsubscription_isEntitled",
@@ -1064,6 +1533,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-subscriptions:TenantSubscription"
         },
+        {
+          "kind": "api",
+          "operation": "replacePlanVersion",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-subscriptions:TenantSubscription"
+        },
         {
           "kind": "api",
           "operation": "setMetadata",
@@ -3031,6 +3507,24 @@
       "operation": "isActive",
       "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
     },
+    {
+      "kind": "cli",
+      "name": "subscriptionplan_getTerms",
+      "operation": "getTerms",
+      "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+    },
+    {
+      "kind": "cli",
+      "name": "subscriptionplan_publishTerms",
+      "operation": "publishTerms",
+      "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+    },
+    {
+      "kind": "cli",
+      "name": "subscriptionplan_getVersionInForce",
+      "operation": "getVersionInForce",
+      "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
+    },
     {
       "kind": "cli",
       "name": "subscriptionplan_getFeatureGrants",
@@ -3085,6 +3579,46 @@
       "operation": "get",
       "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlan"
     },
+    {
+      "kind": "api",
+      "name": "subscriptionplanversions.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion",
+      "path": "/subscriptionplanversions",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "subscriptionplanversions.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion",
+      "path": "/subscriptionplanversions/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "subscriptionplanversion_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+    },
+    {
+      "kind": "cli",
+      "name": "subscriptionplanversion_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+    },
+    {
+      "kind": "mcp",
+      "name": "subscriptionplanversion_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+    },
+    {
+      "kind": "mcp",
+      "name": "subscriptionplanversion_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-subscriptions:SubscriptionPlanVersion"
+    },
     {
       "kind": "api",
       "name": "tenantsubscriptions.list",
@@ -3147,6 +3681,12 @@
       "operation": "delete",
       "objectName": "@happyvertical/smrt-subscriptions:TenantSubscription"
     },
+    {
+      "kind": "cli",
+      "name": "tenantsubscription_replacePlanVersion",
+      "operation": "replacePlanVersion",
+      "objectName": "@happyvertical/smrt-subscriptions:TenantSubscription"
+    },
     {
       "kind": "cli",
       "name": "tenantsubscription_isEntitled",
@@ -3640,14 +4180,14 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 13,
+    "foreignKeyFields": 15,
     "crossPackageRefFields": 6,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 80
+    "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## 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\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",
   "browser": {
     "status": "server-only",
     "issues": [