@happyvertical/smrt-commerce 0.57.2 → 0.57.4

package/dist/smrt-knowledge.json

@@ -3,27 +3,32 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-commerce",
-  "packageVersion": "0.57.2",
+  "packageVersion": "0.57.4",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "b838f1ec7f7691369a45a89993551f3b5b293bafa8787f692fcde405db12eb8e",
-    "packageJson": "0c5d8fbc05319737872531d0c54d6d0aef007e9ae4f3c364dde5c14c8752ead0",
-    "agents": "db9d73082925a67f2045eb7d81f371020986426ec073b136f109f5c896190338",
+    "manifest": "cfcb8d19b0cc6346fa3691630e4d39e76baa07515b4a6a14936c3c13c4467102",
+    "packageJson": "e12000397a9b930d72ec4fef92463a08d5b8f93a2815ec5a9a34bbd88663a0cd",
+    "agents": "f6e250043ec3384326ee0cbbf8c801c90a1fdf9d74ac42810e86ac320a8a8cf7",
     "moduleDoc:agents/customer-vendor-ui.md": "2b22e519411a16d8c493496fc168da77b9acd25f6077ea8fbac00cfee3a3501c",
-    "moduleDoc:README.md": "cb679617ad121b62cdd24d973aeb95b001a52c80efe544219e0755304939c9e5",
+    "moduleDoc:README.md": "7f56bd7667e5270acb18dc2b961f382a9e1bc450b98f7e7b3828c5bc8d7b050c",
     "moduleDoc:agents/invoice-quantity.md": "3a5fbb464c8fe63acc021b2259ba36f052bb22c49b29e503639c5316814e2028",
-    "moduleDoc:agents/payment-allocations.md": "46c0b921f0e40060cd1caec2dcefb01ed6612e31e4bf220a1a0b61e4e2a58212",
+    "moduleDoc:agents/historical-sales.md": "b26b38a78ac0bdaeffb4279f06834aa1223698e1001cba2afb9defe4f8466dbe",
+    "moduleDoc:agents/payment-allocations.md": "679894f603f62522515bce338741bafda3f10d16ef0b817b105dc2e732471fdb",
     "moduleDoc:agents/tax-codes.md": "6b07282f0ac93db4fd42ddb4a9551d880e24ec2bd2fae9d06c06561313b3cb9f",
     "moduleDoc:agents/document-money.md": "7f198737c66d190dbdc9cc9a3dbef460fb7c9fb8ee47dd0eaaadde2f2ba91d47",
     "moduleDoc:agents/money-upgrade.md": "904e218a271d4a8d36a47a50f5f26802a9cf8ba7a69daf7d8857b6b2e4ca814d",
-    "moduleDoc:agents/contract-money.md": "21cbd647e47dda6c0e5c51123e89ed1317282ea6ad0f3a6679b320b73264e5d2",
-    "moduleDoc:agents/money-model.md": "1adb9ed97d688832274596d21dd60ea13df1cb07770b1619cdd03f8683eb1102",
-    "moduleDoc:agents/money-calculator.md": "415e5d499d2b81393c9b8720ead35a1c24d52db7e052964deb01449b52486b2d",
+    "moduleDoc:agents/contract-money.md": "3806a844f0ee14fe429ac74880d59e728d6eab2eb991f83743ffcd6669388729",
+    "moduleDoc:agents/money-model.md": "ce996509c0a522aaa2f7fd63e66ae8a9958c2737aafb5578304d6122ca7e996a",
+    "moduleDoc:agents/money-calculator.md": "5cf5e89c926fc8a2ac4c4e65d85c0c4444fd323aa4131259bfe66843da48393d",
     "moduleDoc:agents/commercial-ui.md": "37397f3e3d77c30ef40b0962d606e17fa61b5bb6f57d1cf13cdc26b4fc6a6cbc",
     "moduleDoc:agents/quote-ui.md": "9d1faaa12f39e330294693f5309d9766c593dc0f7ced9e8b1dcaf5c81b066205",
     "moduleDoc:agents/purchasing-ui.md": "d2b413009d466f3320934adf1e30ffbb7278138b859df69635e7c1f77efbbd1c",
-    "moduleDoc:agents/cost-billing.md": "eaedcc68bb5c2ad7994bf1fc873175b6b800a6ca87e04ba6a51e041d4b765561"
+    "moduleDoc:agents/cost-billing.md": "eaedcc68bb5c2ad7994bf1fc873175b6b800a6ca87e04ba6a51e041d4b765561",
+    "moduleDoc:agents/contract-billing-schedules.md": "b9e2cb806c3296d12928279a64119a67b105c57443fc7f57adcd1cf070533e26",
+    "moduleDoc:agents/customer-funds.md": "417af24b9de9c41c89917e3c6e50e324a1baa70de9e45a61772b3d84c8bfeda0",
+    "moduleDoc:agents/observed-purchase-prices.md": "e8e68d733b7b9453b4dbd54e1dcf11e1486b70ee855ac629bb4e6888eb90ca9c",
+    "moduleDoc:agents/received-sales-contract-money.md": "675d728c565346e5d808e8299a55f2543a423853be0ce9abc99dc7041af79570"
   },
   "exports": [
     ".",
@@ -93,7 +98,7 @@
     "smrt"
   ],
   "risks": [
-    "cross-package-refs:17",
+    "cross-package-refs:18",
     "sensitive-fields-excluded",
     "sti-inheritance"
   ],
@@ -1171,6 +1176,57 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "HistoricalCustomerFundsCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsCollection",
+      "collection": "historicalcustomerfundses",
+      "tableName": "historical_customer_funds",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "HistoricalCustomerFundsAllocationCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocationCollection",
+      "collection": "historicalcustomerfundsallocations",
+      "tableName": "historical_customer_funds_allocations",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "HistoricalSalesLineCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:HistoricalSalesLineCollection",
+      "collection": "historicalsaleslines",
+      "tableName": "historical_sales_lines",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "InvoiceCollection",
       "qualifiedName": "@happyvertical/smrt-commerce:InvoiceCollection",
@@ -2995,6 +3051,23 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "PurchasePriceObservationCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:PurchasePriceObservationCollection",
+      "collection": "purchasepriceobservations",
+      "tableName": "purchase_price_observations",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "SalesContractCollection",
       "qualifiedName": "@happyvertical/smrt-commerce:SalesContractCollection",
@@ -3559,6 +3632,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -3647,6 +3740,8 @@
       ],
       "relationships": [],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -3659,6 +3754,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -3828,6 +3940,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:Contract"
         },
+        {
+          "kind": "cli",
+          "name": "contract_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
         {
           "kind": "cli",
           "name": "contract_saveDerived",
@@ -3848,6 +3966,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -4005,6 +4130,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -4109,6 +4254,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -4121,6 +4268,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -4222,6 +4386,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -4380,6 +4551,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -4484,6 +4675,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -4496,6 +4689,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -4597,6 +4807,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -4754,6 +4971,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -4857,6 +5094,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -4869,6 +5108,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -5032,6 +5288,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:Estimate"
         },
+        {
+          "kind": "cli",
+          "name": "estimate_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:Estimate"
+        },
         {
           "kind": "cli",
           "name": "estimate_saveDerived",
@@ -5052,6 +5314,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Estimate"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -5209,6 +5478,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -5312,6 +5601,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -5325,17 +5616,34 @@
       ],
       "methodSignatures": [
         {
-          "name": "initialize",
+          "name": "delete",
           "async": true,
-          "returns": "Promise<this>"
-        },
-        {
-          "name": "isAccepted",
-          "returns": "boolean"
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
         },
         {
-          "name": "isCompleted",
-          "returns": "boolean"
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "initialize",
+          "async": true,
+          "returns": "Promise<this>"
+        },
+        {
+          "name": "isAccepted",
+          "returns": "boolean"
+        },
+        {
+          "name": "isCompleted",
+          "returns": "boolean"
         },
         {
           "name": "isDraft",
@@ -5487,6 +5795,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:Order"
         },
+        {
+          "kind": "cli",
+          "name": "order_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:Order"
+        },
         {
           "kind": "cli",
           "name": "order_saveDerived",
@@ -5507,6 +5821,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Order"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -5664,6 +5985,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -5767,6 +6108,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -5779,6 +6122,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -5942,6 +6302,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:Lease"
         },
+        {
+          "kind": "cli",
+          "name": "lease_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:Lease"
+        },
         {
           "kind": "cli",
           "name": "lease_saveDerived",
@@ -5962,6 +6328,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Lease"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -6119,6 +6492,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -6222,6 +6615,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -6234,6 +6629,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -6397,6 +6809,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:Agreement"
         },
+        {
+          "kind": "cli",
+          "name": "agreement_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:Agreement"
+        },
         {
           "kind": "cli",
           "name": "agreement_saveDerived",
@@ -6417,6 +6835,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Agreement"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -6574,6 +6999,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -6677,6 +7122,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -6689,6 +7136,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -6852,6 +7316,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:SupplierQuote"
         },
+        {
+          "kind": "cli",
+          "name": "supplierquote_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:SupplierQuote"
+        },
         {
           "kind": "cli",
           "name": "supplierquote_saveDerived",
@@ -6872,6 +7342,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:SupplierQuote"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -7029,6 +7506,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -7146,6 +7643,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -7158,6 +7657,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -7321,6 +7837,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:PurchaseOrder"
         },
+        {
+          "kind": "cli",
+          "name": "purchaseorder_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseOrder"
+        },
         {
           "kind": "cli",
           "name": "purchaseorder_saveDerived",
@@ -7341,6 +7863,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseOrder"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -7498,6 +8027,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -7601,6 +8150,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -7613,6 +8164,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -7776,6 +8344,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:WholesaleOrder"
         },
+        {
+          "kind": "cli",
+          "name": "wholesaleorder_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:WholesaleOrder"
+        },
         {
           "kind": "cli",
           "name": "wholesaleorder_saveDerived",
@@ -7798,7 +8372,14 @@
       "withheldSurfaces": [
         {
           "kind": "api",
-          "operation": "initialize",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:WholesaleOrder"
+        },
+        {
+          "kind": "api",
+          "operation": "initialize",
           "code": "lifecycle-method",
           "reason": "`initialize` is a framework lifecycle method, not a distinct operation",
           "objectName": "@happyvertical/smrt-commerce:WholesaleOrder"
@@ -7953,6 +8534,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -8069,6 +8670,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -8081,6 +8684,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -8244,6 +8864,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:ProductionOrder"
         },
+        {
+          "kind": "cli",
+          "name": "productionorder_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:ProductionOrder"
+        },
         {
           "kind": "cli",
           "name": "productionorder_saveDerived",
@@ -8264,6 +8890,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:ProductionOrder"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -8421,6 +9054,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -8525,6 +9178,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "initialize",
         "isAccepted",
         "isCompleted",
@@ -8537,6 +9192,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -8700,6 +9372,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:Cart"
         },
+        {
+          "kind": "cli",
+          "name": "cart_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:Cart"
+        },
         {
           "kind": "cli",
           "name": "cart_saveDerived",
@@ -8720,6 +9398,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Cart"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -8877,6 +9562,26 @@
           "default": "USD",
           "description": "The currency of the amounts."
         },
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or recorded from reviewed original paperwork."
+        },
+        {
+          "name": "receivedPurchaseMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "billingScheduleJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -9071,6 +9776,8 @@
         }
       ],
       "methods": [
+        "delete",
+        "deleteDerived",
         "getRightsSnapshot",
         "initialize",
         "isAccepted",
@@ -9085,6 +9792,23 @@
         "saveDerived"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "deleteDerived",
+          "async": true,
+          "params": [
+            "capability: DocumentMoneyWriteCapability",
+            "options?: object"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "getRightsSnapshot",
           "returns": "LicenseRightsSnapshot"
@@ -9256,6 +9980,12 @@
           "operation": "recalculateTotals",
           "objectName": "@happyvertical/smrt-commerce:LicenseSale"
         },
+        {
+          "kind": "cli",
+          "name": "licensesale_deleteDerived",
+          "operation": "deleteDerived",
+          "objectName": "@happyvertical/smrt-commerce:LicenseSale"
+        },
         {
           "kind": "cli",
           "name": "licensesale_saveDerived",
@@ -9288,6 +10018,13 @@
         }
       ],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "deleteDerived",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:LicenseSale"
+        },
         {
           "kind": "api",
           "operation": "getRightsSnapshot",
@@ -10231,7 +10968,14 @@
           "required": true,
           "columnType": "INTEGER",
           "default": 0,
-          "description": "Tax-exclusive base in integer minor units."
+          "description": "Actual component taxable basis, including prior compound taxes."
+        },
+        {
+          "name": "netMinor",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "description": "Net basis when different from the component taxable basis."
         },
         {
           "name": "taxMinor",
@@ -10889,40 +11633,18 @@
       "risks": []
     },
     {
-      "name": "Invoice",
-      "qualifiedName": "@happyvertical/smrt-commerce:Invoice",
-      "collection": "invoices",
-      "description": "Invoice represents a bill sent to a customer for goods or services.",
-      "tableName": "invoices",
+      "name": "HistoricalCustomerFunds",
+      "qualifiedName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds",
+      "collection": "historicalcustomerfundses",
+      "description": "Retained original cash evidence. It is deliberately not a completed ledger-backed Payment.",
+      "tableName": "historical_customer_funds",
       "packageName": "@happyvertical/smrt-commerce",
       "extends": "SmrtObject",
       "fields": [
-        {
-          "name": "kind",
-          "type": "text",
-          "required": false,
-          "columnType": "TEXT",
-          "default": "invoice",
-          "description": "Invoice or customer credit note."
-        },
-        {
-          "name": "creditedInvoiceId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Invoice",
-          "columnType": "UUID"
-        },
-        {
-          "name": "creditedAmount",
-          "type": "integer",
-          "required": true,
-          "columnType": "INTEGER",
-          "default": 0
-        },
         {
           "name": "tenantId",
           "type": "text",
-          "required": false,
+          "required": true,
           "columnType": "UUID"
         },
         {
@@ -10930,100 +11652,763 @@
           "type": "foreignKey",
           "required": false,
           "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer being billed."
+          "columnType": "UUID"
         },
         {
           "name": "contractId",
           "type": "foreignKey",
           "required": false,
-          "related": "SalesContract",
-          "columnType": "UUID",
-          "description": "The order or agreement this invoice bills for, if any."
+          "related": "Contract",
+          "columnType": "UUID"
         },
         {
-          "name": "invoiceNumber",
+          "name": "sourceKeyHash",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "default": "",
-          "description": "The number printed on the invoice."
+          "columnType": "TEXT"
         },
         {
-          "name": "reference",
+          "name": "kind",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
-        },
-        {
-          "name": "issueDate",
-          "type": "datetime",
-          "required": false,
-          "columnType": "TIMESTAMP",
-          "description": "The date the invoice was issued."
+          "default": "receipt"
         },
         {
-          "name": "dueDate",
-          "type": "datetime",
+          "name": "origin",
+          "type": "text",
           "required": false,
-          "columnType": "TIMESTAMP",
-          "description": "The date payment is expected."
+          "columnType": "TEXT",
+          "default": "historical"
         },
         {
-          "name": "paidDate",
-          "type": "datetime",
+          "name": "paymentId",
+          "type": "foreignKey",
           "required": false,
-          "columnType": "TIMESTAMP",
-          "description": "The date it was paid in full."
+          "related": "Payment",
+          "columnType": "UUID"
         },
         {
-          "name": "subtotal",
-          "type": "integer",
+          "name": "currency",
+          "type": "text",
           "required": false,
-          "columnType": "INTEGER",
-          "default": 0,
-          "description": "The amount before tax."
+          "columnType": "TEXT"
         },
         {
-          "name": "taxAmount",
+          "name": "amountMinor",
           "type": "integer",
-          "required": false,
+          "required": true,
           "columnType": "INTEGER",
-          "default": 0,
-          "description": "The tax charged."
+          "default": 0
         },
         {
-          "name": "providerTaxAmount",
-          "type": "integer",
+          "name": "effectiveOn",
+          "type": "text",
           "required": false,
-          "columnType": "INTEGER",
-          "default": 0
+          "columnType": "TEXT"
         },
         {
-          "name": "totalAmount",
-          "type": "integer",
+          "name": "sourceReceiptId",
+          "type": "foreignKey",
           "required": false,
-          "columnType": "INTEGER",
-          "default": 0,
-          "description": "What the customer owes in all, tax included."
+          "related": "HistoricalCustomerFunds",
+          "columnType": "UUID"
         },
         {
-          "name": "amountPaid",
-          "type": "integer",
+          "name": "sourceCreditNoteId",
+          "type": "foreignKey",
           "required": false,
-          "columnType": "INTEGER",
-          "default": 0,
-          "description": "How much of the total has been paid so far."
+          "related": "Invoice",
+          "columnType": "UUID"
         },
         {
-          "name": "currency",
+          "name": "snapshotJson",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "default": "CAD",
-          "description": "The currency of the invoice."
-        },
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "customerId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Customer",
+          "columnType": "UUID"
+        },
+        {
+          "name": "contractId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Contract",
+          "columnType": "UUID"
+        },
+        {
+          "name": "paymentId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Payment",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceReceiptId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "HistoricalCustomerFunds",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceCreditNoteId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Invoice",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "historicalcustomerfundses.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds",
+          "path": "/historicalcustomerfundses",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "historicalcustomerfundses.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds",
+          "path": "/historicalcustomerfundses/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "historicalcustomerfunds_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds"
+        },
+        {
+          "kind": "cli",
+          "name": "historicalcustomerfunds_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds"
+        },
+        {
+          "kind": "mcp",
+          "name": "historicalcustomerfunds_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds"
+        },
+        {
+          "kind": "mcp",
+          "name": "historicalcustomerfunds_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "HistoricalCustomerFundsAllocation",
+      "qualifiedName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation",
+      "collection": "historicalcustomerfundsallocations",
+      "description": "Original applications have concrete identities; credit-audit records never count twice.",
+      "tableName": "historical_customer_funds_allocations",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "receiptId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "HistoricalCustomerFunds",
+          "columnType": "UUID"
+        },
+        {
+          "name": "creditNoteId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Invoice",
+          "columnType": "UUID"
+        },
+        {
+          "name": "invoiceId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Invoice",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceKeyHash",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "amountMinor",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "effectiveOn",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "origin",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "historical"
+        },
+        {
+          "name": "effect",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "payment"
+        },
+        {
+          "name": "journalId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-ledgers:Journal",
+          "columnType": "UUID"
+        },
+        {
+          "name": "snapshotJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "receiptId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "HistoricalCustomerFunds",
+          "columnType": "UUID"
+        },
+        {
+          "name": "creditNoteId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Invoice",
+          "columnType": "UUID"
+        },
+        {
+          "name": "invoiceId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Invoice",
+          "columnType": "UUID"
+        },
+        {
+          "name": "journalId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-ledgers:Journal",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "historicalcustomerfundsallocations.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation",
+          "path": "/historicalcustomerfundsallocations",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "historicalcustomerfundsallocations.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation",
+          "path": "/historicalcustomerfundsallocations/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "historicalcustomerfundsallocation_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation"
+        },
+        {
+          "kind": "cli",
+          "name": "historicalcustomerfundsallocation_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation"
+        },
+        {
+          "kind": "mcp",
+          "name": "historicalcustomerfundsallocation_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation"
+        },
+        {
+          "kind": "mcp",
+          "name": "historicalcustomerfundsallocation_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "HistoricalSalesLine",
+      "qualifiedName": "@happyvertical/smrt-commerce:HistoricalSalesLine",
+      "collection": "historicalsaleslines",
+      "description": "An immutable source line with explicit unknowns, never a calculated InvoiceLineItem.",
+      "tableName": "historical_sales_lines",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "invoiceId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Invoice",
+          "columnType": "UUID"
+        },
+        {
+          "name": "creditedLineId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "HistoricalSalesLine",
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceKeyHash",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "description",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "netMinor",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "taxMinor",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "grossMinor",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "quantityText",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "unitRateText",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceFieldsJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "moneySnapshotId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "invoiceId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Invoice",
+          "columnType": "UUID"
+        },
+        {
+          "name": "creditedLineId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "HistoricalSalesLine",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "historicalsaleslines.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine",
+          "path": "/historicalsaleslines",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "historicalsaleslines.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine",
+          "path": "/historicalsaleslines/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "historicalsalesline_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine"
+        },
+        {
+          "kind": "cli",
+          "name": "historicalsalesline_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine"
+        },
+        {
+          "kind": "mcp",
+          "name": "historicalsalesline_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine"
+        },
+        {
+          "kind": "mcp",
+          "name": "historicalsalesline_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "Invoice",
+      "qualifiedName": "@happyvertical/smrt-commerce:Invoice",
+      "collection": "invoices",
+      "description": "Invoice represents a bill sent to a customer for goods or services.",
+      "tableName": "invoices",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "moneyAuthority",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "calculated",
+          "description": "Whether amounts were calculated or retained from an original issued invoice."
+        },
+        {
+          "name": "historicalSalesMoneyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "historicalSourceKeyHash",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "invoice",
+          "description": "Invoice or customer credit note."
+        },
+        {
+          "name": "creditedInvoiceId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Invoice",
+          "columnType": "UUID"
+        },
+        {
+          "name": "creditedAmount",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "retentionStateJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "customerId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Customer",
+          "columnType": "UUID",
+          "description": "The customer being billed."
+        },
+        {
+          "name": "contractId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "SalesContract",
+          "columnType": "UUID",
+          "description": "The order or agreement this invoice bills for, if any."
+        },
+        {
+          "name": "invoiceNumber",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "The number printed on the invoice."
+        },
+        {
+          "name": "reference",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "issueDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "The date the invoice was issued."
+        },
+        {
+          "name": "dueDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "The date payment is expected; null when the original source did not establish it."
+        },
+        {
+          "name": "paidDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "The date it was paid in full."
+        },
+        {
+          "name": "subtotal",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0,
+          "description": "The amount before tax."
+        },
+        {
+          "name": "taxAmount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0,
+          "description": "The tax charged."
+        },
+        {
+          "name": "providerTaxAmount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "totalAmount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0,
+          "description": "What the customer owes in all, tax included."
+        },
+        {
+          "name": "amountPaid",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0,
+          "description": "How much of the total has been paid so far."
+        },
+        {
+          "name": "currency",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "CAD",
+          "description": "The currency of the invoice."
+        },
         {
           "name": "lineAmountType",
           "type": "text",
@@ -11227,6 +12612,7 @@
         "getAmountDue",
         "getArJournal",
         "getBalance",
+        "getPayableFacts",
         "initialize",
         "isDraft",
         "isOverdue",
@@ -11286,6 +12672,10 @@
           "name": "getBalance",
           "returns": "number"
         },
+        {
+          "name": "getPayableFacts",
+          "returns": "any"
+        },
         {
           "name": "initialize",
           "async": true,
@@ -11447,6 +12837,12 @@
           "operation": "rebindMoneyRead",
           "objectName": "@happyvertical/smrt-commerce:Invoice"
         },
+        {
+          "kind": "cli",
+          "name": "invoice_getPayableFacts",
+          "operation": "getPayableFacts",
+          "objectName": "@happyvertical/smrt-commerce:Invoice"
+        },
         {
           "kind": "cli",
           "name": "invoice_saveDerived",
@@ -11611,6 +13007,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-commerce:Invoice"
         },
+        {
+          "kind": "api",
+          "operation": "getPayableFacts",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Invoice"
+        },
         {
           "kind": "api",
           "operation": "initialize",
@@ -12221,6 +13624,12 @@
           "columnType": "TEXT",
           "default": "payment"
         },
+        {
+          "name": "customerFundsJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "tenantId",
           "type": "text",
@@ -12398,6 +13807,7 @@
       ],
       "methods": [
         "cancel",
+        "delete",
         "getJournal",
         "initialize",
         "isCompleted",
@@ -12414,6 +13824,14 @@
           "name": "cancel",
           "returns": "void"
         },
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: SmrtDeleteOptions"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "getJournal",
           "async": true,
@@ -12775,9 +14193,18 @@
         }
       ],
       "methods": [
+        "delete",
         "save"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "params": [
+            "options?: SmrtDeleteOptions"
+          ],
+          "returns": "Promise<void>"
+        },
         {
           "name": "save",
           "async": true,
@@ -14031,6 +15458,112 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "PurchasePriceObservation",
+      "qualifiedName": "@happyvertical/smrt-commerce:PurchasePriceObservation",
+      "collection": "purchasepriceobservations",
+      "description": "Original purchase evidence with explicitly unavailable monetary aggregates.",
+      "tableName": "purchase_price_observations",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "sourceIdentity",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "vendorId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "snapshotJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "completionJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "delete",
+        "save",
+        "saveObserved"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        },
+        {
+          "name": "saveObserved",
+          "async": true,
+          "params": [
+            "capability: any"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-commerce:PurchasePriceObservation"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-commerce:PurchasePriceObservation"
+        },
+        {
+          "kind": "api",
+          "operation": "saveObserved",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-commerce:PurchasePriceObservation"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "TaxCode",
       "qualifiedName": "@happyvertical/smrt-commerce:TaxCode",
@@ -16797,6 +18330,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:Contract"
     },
+    {
+      "kind": "cli",
+      "name": "contract_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:Contract"
+    },
     {
       "kind": "cli",
       "name": "contract_saveDerived",
@@ -16999,6 +18538,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:Estimate"
     },
+    {
+      "kind": "cli",
+      "name": "estimate_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:Estimate"
+    },
     {
       "kind": "cli",
       "name": "estimate_saveDerived",
@@ -17121,6 +18666,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:Order"
     },
+    {
+      "kind": "cli",
+      "name": "order_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:Order"
+    },
     {
       "kind": "cli",
       "name": "order_saveDerived",
@@ -17243,6 +18794,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:Lease"
     },
+    {
+      "kind": "cli",
+      "name": "lease_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:Lease"
+    },
     {
       "kind": "cli",
       "name": "lease_saveDerived",
@@ -17365,6 +18922,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:Agreement"
     },
+    {
+      "kind": "cli",
+      "name": "agreement_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:Agreement"
+    },
     {
       "kind": "cli",
       "name": "agreement_saveDerived",
@@ -17487,6 +19050,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:SupplierQuote"
     },
+    {
+      "kind": "cli",
+      "name": "supplierquote_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:SupplierQuote"
+    },
     {
       "kind": "cli",
       "name": "supplierquote_saveDerived",
@@ -17609,6 +19178,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:PurchaseOrder"
     },
+    {
+      "kind": "cli",
+      "name": "purchaseorder_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:PurchaseOrder"
+    },
     {
       "kind": "cli",
       "name": "purchaseorder_saveDerived",
@@ -17731,6 +19306,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:WholesaleOrder"
     },
+    {
+      "kind": "cli",
+      "name": "wholesaleorder_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:WholesaleOrder"
+    },
     {
       "kind": "cli",
       "name": "wholesaleorder_saveDerived",
@@ -17853,6 +19434,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:ProductionOrder"
     },
+    {
+      "kind": "cli",
+      "name": "productionorder_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:ProductionOrder"
+    },
     {
       "kind": "cli",
       "name": "productionorder_saveDerived",
@@ -17975,6 +19562,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:Cart"
     },
+    {
+      "kind": "cli",
+      "name": "cart_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:Cart"
+    },
     {
       "kind": "cli",
       "name": "cart_saveDerived",
@@ -18097,6 +19690,12 @@
       "operation": "recalculateTotals",
       "objectName": "@happyvertical/smrt-commerce:LicenseSale"
     },
+    {
+      "kind": "cli",
+      "name": "licensesale_deleteDerived",
+      "operation": "deleteDerived",
+      "objectName": "@happyvertical/smrt-commerce:LicenseSale"
+    },
     {
       "kind": "cli",
       "name": "licensesale_saveDerived",
@@ -18569,6 +20168,126 @@
       "operation": "get",
       "objectName": "@happyvertical/smrt-commerce:FulfillmentLineItem"
     },
+    {
+      "kind": "api",
+      "name": "historicalcustomerfundses.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds",
+      "path": "/historicalcustomerfundses",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "historicalcustomerfundses.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds",
+      "path": "/historicalcustomerfundses/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "historicalcustomerfunds_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds"
+    },
+    {
+      "kind": "cli",
+      "name": "historicalcustomerfunds_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds"
+    },
+    {
+      "kind": "mcp",
+      "name": "historicalcustomerfunds_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds"
+    },
+    {
+      "kind": "mcp",
+      "name": "historicalcustomerfunds_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFunds"
+    },
+    {
+      "kind": "api",
+      "name": "historicalcustomerfundsallocations.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation",
+      "path": "/historicalcustomerfundsallocations",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "historicalcustomerfundsallocations.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation",
+      "path": "/historicalcustomerfundsallocations/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "historicalcustomerfundsallocation_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation"
+    },
+    {
+      "kind": "cli",
+      "name": "historicalcustomerfundsallocation_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation"
+    },
+    {
+      "kind": "mcp",
+      "name": "historicalcustomerfundsallocation_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation"
+    },
+    {
+      "kind": "mcp",
+      "name": "historicalcustomerfundsallocation_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalCustomerFundsAllocation"
+    },
+    {
+      "kind": "api",
+      "name": "historicalsaleslines.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine",
+      "path": "/historicalsaleslines",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "historicalsaleslines.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine",
+      "path": "/historicalsaleslines/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "historicalsalesline_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine"
+    },
+    {
+      "kind": "cli",
+      "name": "historicalsalesline_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine"
+    },
+    {
+      "kind": "mcp",
+      "name": "historicalsalesline_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine"
+    },
+    {
+      "kind": "mcp",
+      "name": "historicalsalesline_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:HistoricalSalesLine"
+    },
     {
       "kind": "api",
       "name": "invoices.list",
@@ -18637,6 +20356,12 @@
       "operation": "rebindMoneyRead",
       "objectName": "@happyvertical/smrt-commerce:Invoice"
     },
+    {
+      "kind": "cli",
+      "name": "invoice_getPayableFacts",
+      "operation": "getPayableFacts",
+      "objectName": "@happyvertical/smrt-commerce:Invoice"
+    },
     {
       "kind": "cli",
       "name": "invoice_saveDerived",
@@ -19712,14 +21437,14 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 37,
-    "crossPackageRefFields": 17,
+    "foreignKeyFields": 47,
+    "crossPackageRefFields": 18,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 224
+    "uuidColumns": 262
   },
-  "agentDoc": "# @happyvertical/smrt-commerce\n\nE-commerce with Contract STI hierarchy, invoice lifecycle, payment tracking, payout remittance, and optional ledger integration.\n\n## Models\n\n- **Customer** / **Vendor**: linked to Profile via string ID (not FK). `contacts` (JSON) is written via [`savePartyContacts()`](agents/customer-vendor-ui.md#contact-rows-3501). Customer has creditLimit, paymentTerms, customerType (DTC / WHOLESALE / RETAIL). Vendor has leadTimeDays, minimumOrder, and `payoutAddresses: Record<string, string>` — a flat map from payout-rail-qualified currency code (`USDC-base`, `BTC`, `USD-stripe`, ...) to destination string (EVM address, BTC address, Stripe Connect account id, IBAN). Use `getPayoutAddress(currency)` for a `Map.get`-style lookup; missing entries return `undefined` (caller decides skip-vs-error).\n- **Contract**: concrete STI base. Abstract **SalesContract** owns `customerId`; **PurchaseContract** owns `vendorId`. `channelId` is open-ended. Before upgrade, run `preflightCommercePartyLinks(db)` and repair linked base rows, stray parties, and wrong-branch links. See [README](README.md).\n- **WholesaleOrder**: B2B order. Conventional pairing — customer has `customerType: 'wholesale'`, NET-30/60 terms, delivered via wholesale-portal channel.\n- **ProductionOrder**: manufacturing equivalent of a PurchaseOrder — commission your factory to make finished goods. Consumes raw materials per BOM (`@happyvertical/smrt-manufacturing`) and produces SKU stock (`@happyvertical/smrt-inventory`).\n- **Cart**: transient order-in-progress. Same shape as Order; the application promotes the row from `_meta_type: Cart` to `_meta_type: Order` at checkout instead of copying data between tables.\n- **LicenseSale**: industry-neutral licensing primitive. Carries an *immutable* rights snapshot (`rightsMedium`, `rightsDistributionScope`, `rightsExclusivity`, `rightsDuration`, `rightsTerritory`, `rightsSublicensing`, `rightsDerivatives` — typed `Meta<T>` fields), licensee identity (`licenseeEmail`, optional `licenseeLegalEntity` / `licenseeJurisdiction`), and a signed-PDF reference (`pdfUrl`, `pdfHash`, optional `onChainHashRegistryRef`). Once saved at `ContractStatus.ACCEPTED`, the rights snapshot is frozen — mutating any of the seven rights fields and re-saving throws. The only legal transition out of ACCEPTED is `revoke()` (moves to CANCELLED without touching rights). Useful for stock media, music licensing, code-asset marketplaces, license keys, anywhere rights are sold for a fee.\n- **ContractLineItem**: items on contracts.\n- **Invoice**: status machine `DRAFT → SENT → VIEWED → PARTIAL → PAID` (also OVERDUE, CANCELLED, WRITTEN_OFF). `recognizeRevenue()` creates balanced AR journal entry (DR: Accounts Receivable, CR: Revenue, CR: Tax Payable).\n- **InvoiceLineItem**: fractional-quantity line items with safe minor-unit validation/recalculation on save; the existing-column migration is documented in [invoice quantity persistence](agents/invoice-quantity.md).\n- **Payment** / **PaymentAllocation**: tracks payments against invoices (status: see Gotchas). Carries optional backend-adapter fields for PaymentBackend-routed flows: `backendId` (rail adapter id — `base-usdc`, `btc`, `stripe`, distinct from `externalProvider` which names an accounting sync destination), `backendTxRef` (chain tx hash or gateway settlement id), `nativeAmount` / `nativeCurrency` (what actually arrived), `usdAtQuote` / `usdAtConfirmation` (drift accounting for volatile-currency rails). `Payment.usdDrift()` returns the confirmation - quote delta, or `0` when either side is unset.\n- **PaymentInstrument**: reusable saved payment method (\"card on file\"). Stores only provider references and non-sensitive display metadata (`providerCustomerId`, `providerPaymentMethodId`, brand / last4 / expiry), never raw card data. `isDefault` is domain-managed, not API-writable: `PaymentInstrumentCollection.setDefaultForCustomer(customerId, instrumentId)` validates the target and clears the customer's other defaults (one per customer).\n- **PaymentIntent**: short-lived pre-payment commitment with multi-option semantics. Locks a USD price for a fixed window (default 15 minutes) and lists one or more `PaymentOption`s describing different rails (`backendId`, `currency`, `payTo`, `nativeAmount`, optional `chain` / `memo` / `x402Capable` / `expiresAt`). First option to receive payment wins; the others are implicitly retired. State machine `awaiting_payment → paid → (issued | retired)` plus `expired` and `cancelled`. Mutate via dedicated `markPaid` / `markIssued` / `expire` / `cancel` / `retire` helpers — direct status assignment bypasses the invariant checks. Idempotency: see the natural-key Gotcha.\n- **Payout**: operator-to-supplier remittance. Distinct from Payment because direction, status machine, and chain semantics differ. Status machine `pending → sent → confirmed → failed` (failed is terminal but resettable via `resetFromFailed()` after fixing the underlying problem). References source `paymentId` (plain string) and destination `vendorId` (foreign key). Amount invariant `supplierNet === grossAmount - operatorFee` enforced exactly on save (integer minor units, no tolerance — #2401). `PayoutCollection.createFromPayment()` is the typical entry point; it pulls native amount / currency from the source Payment.\n- **Fulfillment** / **FulfillmentLineItem**: shipment/delivery tracking.\n\n## Recipes (#3590)\n\n`src/recipes.ts` declares four minimal `SmrtRecipe`s, emitted into the built\n`manifest.json` and `smrt-knowledge.json` `recipes`: `commerce.customers`\n(Customer), `commerce.vendors` (Vendor), `commerce.sales` (Order, requires\ncustomers), `commerce.purchases` (PurchaseOrder, requires vendors). Headers\nonly; line items, fulfilment, invoices, and payments are later recipes. Each\nhas user-facing help in `src/<name>.recipe.md` (#3591), and the fields those\nrecipes show carry `@field({ description })` text; keep both in plain\nlanguage for end users and update them when a recipe's fields change. See\n[core recipes](../core/agents/recipes.md).\n\nSee [payment allocation integrity](agents/payment-allocations.md) for atomic splits,\nretry identity, parent corrections and supported dialects.\nSee [tax codes](agents/tax-codes.md) for tenant-owned rate components, default codes,\nand the standard codes every tenant gets.\nSee [document money persistence](agents/document-money.md) for the one money\nmodel: tax-code resolution, atomic aggregate writes, issued snapshots, and\nfrozen fields. Every Invoice and Contract money write needs a tenant. Host\nbootstrap is `ensureCommerceTenant(db, tenantId, { cookbook })`, which returns\n`{ tenantId }`. Money data written by an earlier version is refused with\n`COMMERCE_DATA_NEEDS_UPGRADE` until `smrt db:upgrade-commerce-money` converts\nit; see [money data upgrade](agents/money-upgrade.md).\nSee [Contract money persistence](agents/contract-money.md) for the Contract\naggregate and purchase recoverability.\n\n## Ledger Integration\n\n`@happyvertical/smrt-ledgers` is a regular dependency, loaded lazily via dynamic `import()` (never a static import) so the package graph stays a DAG (#1582). Invoice stores `arJournalId` and `revenueJournalId` as string references. `recognizeRevenue()` creates a balanced AR journal entry; `getArJournal()` returns null when no journal has been recognized yet.\n\n## Billing-period close (#3060)\n\n`src/billing/` closes periods from smrt-subscriptions charges; see the README\nfor usage.\n\n- **Port, not provider.** Period close, events, and credit checkout call only\n  the `BillingProvider` port (integer minor units). `stripe.ts` adapts\n  `@happyvertical/accounting`, which takes currency *major* units; convert with\n  `units.ts` and never hand-roll a Stripe call here. `units.ts` exponents are\n  an explicit ISO 4217 table matching the SDK's, never `Intl` display digits\n  (CLDR differs for IQD, MGA, … and drifts by ICU release). The SDK's\n  `*Minor` fields are already ISO minor units. Capabilities a rail may lack\n  (`chargeSavedPaymentMethod`, `createSetupCheckout`, `getCheckout`,\n  `setDefaultPaymentMethod`, `markInvoiceUncollectible`) are optional port\n  methods: detect them by presence, and keep additions optional (#3139).\n  `sendAndReconcile` refuses a provider invoice whose subtotal or total\n  disagrees with the local invoice.\n- **Replay safety is identity.** Close, invoice, line, payment, allocation,\n  and claim ids are `deterministicId()`s; `BillingLineSource` (conflict key\n  `source_type, source_id`) is the only double-billing guard, so never bill a\n  source without claiming it, and never widen that key. Each close step is\n  persisted before the next; `acquireCloseLease()` serializes workers. A\n  close that nets to a credit keeps its claims and ends `carried_forward`;\n  its subtotal is a `credit_carry_forward` source for the payer's next billed\n  close, which marks the carried close `completed`.\n- **Cycles and flat-plan coverage (#3116).** `cycles.ts` is the schedule\n  (pure; `BillingAccount.billingAnchorAt`, null = calendar months). A close\n  with no period closes each payer's `lastEndedBillingPeriod()`. Flat-plan\n  claims are the exception to \"id from the source\": their `sourceId` is\n  `<subscriptionId>:seq:<chainSequence>` and their `periodStart/End` is the\n  exact time they bill. `claimFlatWindow()` reads the last number, then the\n  coverage (claims ending after the window start), claims one gap as number\n  n + 1, and retries on conflict; reading in that order is what makes it\n  safe. That numbering, not the period, stops overlaps when schedules or\n  payers change — never claim a flat plan outside it, and keep both reads\n  bounded (no whole-history scans). Each numbered claim is its own invoice\n  line keyed `lineKey|periodStart` (a function of the claim alone, so a\n  resumed close rebuilds the same line ids). Proration is\n  `prorateMinorUnits()` (half up, BigInt) against the period's full cycle.\n- **System tables.** `BillingAccount`, `BillingPeriodClose`, and\n  `BillingLineSource` are not tenant-scoped and have no generated surface.\n  Collections stay unexported; models are root exports (#3082). Invoices,\n  payments, and journals are written in the seller's tenant; payer-owned\n  subscriptions and credit grants in a system context, only after\n  verification.\n- **Events** use smrt-jobs' delivery inbox under provider\n  `<name>-billing:<sellerTenantId>` and a provider-filtered\n  `ForgeProjectionRuntime`, so a runtime never claims another seller's\n  events; any other runtime sharing the inbox must pass `providers` too. Only\n  events this package acts on are stored: foreign checkouts are `ignored`,\n  and only `smrt_*` checkout metadata is kept; it is\n  HMAC-signed with the webhook secret at creation (empty values are omitted:\n  Stripe drops them), so another integration on the same account cannot forge\n  a credit purchase or a card setup; credit is granted only when the\n  collected total equals it plus provider tax. Checkout amounts come from the\n  re-read session (`getCheckout()`), never the Stripe event, whose amounts are\n  in Stripe's unit. Rotating the webhook secret strands in-flight checkouts\n  (up to 24 h). `observe()` re-reads provider state, so ordering never depends\n  on delivery order; the only provider writes in `observe()` are idempotent\n  (making a saved card the default). The standing hook runs inside the event\n  transaction and must be idempotent.\n- **Card on file and top-ups (#3139).** A saved card is the payer customer's\n  default `PaymentInstrument` (seller tenant, id from the provider method).\n  `autoChargeInvoices` bills such payers `charge_automatically`, decided once\n  and saved as `Invoice.collectionMethod` before the first push, which every\n  retry reuses (never recompute it: a lost push response would record a\n  method the provider was not asked for, #3190); activation follows `paid`, never send. An auto top-up attempt\n  is a `PENDING` `Payment` (`reference` `auto-top-up:<policyId>`, id from the\n  policy and `count()` of its attempts) inserted before the charge, so racing\n  evaluations derive one id and one charge; the charge key is derived from\n  that id. `applyAutoTopUpOutcome()` must run in a transaction and starts with\n  a conditional `UPDATE … WHERE status = 'pending'` row lock, so the hook and\n  the `payment` webhook settle once; the grant is keyed by the charge key.\n  Never settle an attempt outside that function. Taxed accounts are charged\n  with provider tax by default (#3194): the attempt row holds the credit\n  (the charge subtotal), the tax is journaled to tax payable at settlement,\n  and the attempt's tax decision is recorded in its `notes` so a re-drive\n  repeats the same charge request (the provider refuses a key reused with\n  different tax). `claimAttempt()` is the only place that decides a\n  skip and reports it (`onAutoTopUpSkipped`); `cardOnFile()` and period close\n  use `defaultCardInstrument()` — never copy that predicate. A provider write-off moves the local invoice to\n  `WRITTEN_OFF` (a later payment, by card or on a rail (#3188), is recorded\n  and reinstates the payer; the status stays, so \"paid in full\" for a\n  written-off invoice is read from its allocations).\n- **Billing invoices are money-model invoices.** The provider taxes them\n  (`providerTaxAmount`, server-managed, not API-writable, added to line tax),\n  so every billing line is an explicit `taxMode: 'override'` to the seller's\n  `out-of-scope` code. Charges are written before credits so the running\n  subtotal never goes negative, and provider tax is written in the save that\n  issues the invoice. Revenue posting is idempotent. `ledger.bookCurrency` is\n  required (ISO 4217, validated by `BillingRuntime`) and must equal the\n  billing currency. `toAccountingInput({ mapping })` emits major units.\n- **Payment rails (#3138).** A runtime has one issuing `provider` and any\n  number of `paymentProviders` (unique names, one inbox namespace each; a\n  provider with `capabilities.issuesInvoices === false` can never issue).\n  `observe()` resolves the provider from the delivery namespace, never the\n  payload. Crypto rails implement the port over `@happyvertical/payments`'\n  `CryptoCheckoutGateway`; never call BTCPay (or any gateway) from here.\n  Settlement is decided by the pure `decideAttempt()` from gateway state and\n  `paymentPolicy` — the gateway's `settled` is authoritative and nothing here\n  counts confirmations. A `BillingPaymentAttempt` (`(provider, checkout_id)`\n  deterministic id) records every state and settles once; grants and payments\n  are keyed by checkout id. Invoice payments close the issuer's invoice out of\n  band in `observe()` (idempotent) before `project()` records the payment, and\n  `settlePaidInvoice` skips (records nothing for) a `paidOutOfBand` invoice\n  the rail latched with `outOfBandRequestedAt`; other out-of-band closes are\n  recorded as `OTHER` payments. Rails never save cards or charge tax: a taxed\n  credit purchase on a rail needs an explicit `automaticTax: false`. Exceptions are flags for operators;\n  nothing reverses or refunds automatically.\n- **Known limits**: write-offs post no bad-debt journal (AR stays until paid\n  or journaled by an operator); discounts still reach Stripe as negative lines (the SDK's\n  line `discount` would change the lines a replayed push reconciles, so it\n  needs its own migration); `RetailCharge` has no adjustment ledger. Flat\n  plans are monthly, in arrears; plan changes are not prorated (#3119).\n\n## Cross-Package References\n\n- `customerId` → `@foreignKey('Customer')` (hard reference within package)\n- `vendorId` → `@foreignKey('Vendor')` on PurchaseContract only\n- `profileId` → plain string to smrt-profiles\n- `arJournalId`, `revenueJournalId` → plain string to smrt-ledgers\n- `skuId` (on `PaymentIntent`, `LicenseSale`) → plain string to smrt-products\n- `paymentId` (on `PaymentIntent`, `Payout`, `LicenseSale`) → plain string to `Payment` (same package, but kept as plain string for cross-model consistency)\n- `vendorId` on `Payout` → `@foreignKey(Vendor)` (hard reference within package)\n- Billing records reference tenants with `@crossPackageRef('@happyvertical/smrt-users:Tenant')` and charges, plan periods, and adjustments by plain `sourceId`\n\n## Gotchas\n\n- **Optional tenancy**: all models `@TenantScoped({ mode: 'optional' })` + nullable tenantId\n- **Money units and arithmetic**: money fields use signed integer minor units; rates and quantities remain decimal where their contracts require them. Exact rounding, tax-code resolution, safe-integer validation, and journal units are defined in the [commercial money model](agents/money-model.md) and [money calculator](agents/money-calculator.md). Do not reintroduce floating-point tolerances on money paths.\n- **Money documents need a tenant**: models are optionally tenant-scoped, but every Invoice and Contract money write requires one (`MoneyValidationError` `INVALID_MONEY_INPUT`, `Commerce money documents require a tenant`).\n- **Earlier-version money data is refused**: never add a read or conversion path for it. Detection and the one-shot upgrade are in [money data upgrade](agents/money-upgrade.md).\n- **Book currency is required**: `recognizeRevenue()` and `cancelWithRevenueReversal()` take a required `bookCurrency`, which must equal the invoice currency.\n- **Asset-native amounts stay outside line rescales**: `Payment.nativeAmount` and `PaymentIntent.paymentOptions[].nativeAmount` are per-asset values identified by `nativeCurrency`; normalize each asset to its own minor unit before any type conversion, and never apply the commerce ×100 line-money rescale to them.\n- **Invoice controls payment status**: not the Payment model — use `Invoice.updatePaymentStatus()`\n- **Tax comes from tax codes**: the server resolves each line's code and computes line tax and header totals; client totals and a line's stored `taxRate` are never inputs\n- **Profile linking**: separate `ProfileCollection.create()` needed to fetch actual Profile object\n- **PaymentIntent natural key**: `conflictColumns: ['tenant_id', 'offering_ref', 'licensee_email', 'idempotency_key']` — a retried `create` with the same tuple upserts the existing row. Use `PaymentIntentCollection.getOrCreateByIdempotencyKey()` to branch on `{ intent, created }`. Empty natural-key inputs (e.g. blank `idempotencyKey`) disable dedup by design.\n- **Payout state-machine guards**: `markSent` requires a non-empty `backendTxRef`; `markConfirmed` only valid from `SENT`; `markFailed` only valid from `PENDING` / `SENT` (a confirmed payout can't fail — that path is a refund). `resetFromFailed()` is the dedicated escape hatch from `FAILED` back to `PENDING` after an operator fixes the underlying problem; it clears `backendTxRef` so the next attempt picks up a fresh one.\n- **LicenseSale immutability**: rights snapshot freezes on save-with-status-ACCEPTED. The captured snapshot lives in a module-scoped `WeakMap<LicenseSale, string>` so it doesn't interact with the schema or round-trip through `_meta_data`. Drafts (status != ACCEPTED) remain mutable. To \"change\" an issued license: `revoke()` it, then issue a new `LicenseSale` row.\n- **Vendor.payoutAddresses normalization**: the constructor accepts either a `Record<string, string>` or a pre-serialized JSON string. `initialize()` re-normalizes after the framework's option-override pass; `save()` re-normalizes defensively against direct field assignment. Non-string values inside the input map are silently dropped to preserve the typed invariant downstream.\n\n## Commercial UI\n\n`CustomerSelect`/`VendorSelect` are the registered selectors for Customer and\nVendor (`selects` in `src/ui.ts`); models carry `ui.widget` / `ui.format` hints. See\n[customer/vendor UI](agents/customer-vendor-ui.md#selectors-3602).\n\nSee [commercial UI composition](agents/commercial-ui.md) for native form recovery, amount compatibility and backend ownership. Package-owned guides under `agents/` ship with the package.\n\n## Quote and estimate UI\n\n`src/svelte/quote-types.ts` separates unparsed draft strings from explicit\nminor-unit revision DTOs. Native row submitters, caller-owned retry identity and\nextension conventions are documented in [agents/quote-ui.md](agents/quote-ui.md).\n\n## Purchasing UI\n\n`PurchaseOrderEditor` preserves allocation IDs and explicit zeroes, including\nretained reduction rows; the server validates review fingerprints before recording.\nSee [agents/purchasing-ui.md](agents/purchasing-ui.md) for caller responsibilities.\n\n## Exact cost billing\n\nPure signed cost billing and explicit tax rounding are available through the\nindependent `cost-billing` subpath; see [contract](agents/cost-billing.md).\n",
+  "agentDoc": "# @happyvertical/smrt-commerce\n\nE-commerce with Contract STI hierarchy, invoice lifecycle, payment tracking, payout remittance, and optional ledger integration.\n\n## Models\n\n- **Customer** / **Vendor**: linked to Profile via string ID (not FK). `contacts` (JSON) is written via [`savePartyContacts()`](agents/customer-vendor-ui.md#contact-rows-3501). Customer has creditLimit, paymentTerms, customerType (DTC / WHOLESALE / RETAIL). Vendor has leadTimeDays, minimumOrder, and `payoutAddresses: Record<string, string>` — a flat map from payout-rail-qualified currency code (`USDC-base`, `BTC`, `USD-stripe`, ...) to destination string (EVM address, BTC address, Stripe Connect account id, IBAN). Use `getPayoutAddress(currency)` for a `Map.get`-style lookup; missing entries return `undefined` (caller decides skip-vs-error).\n- **Contract**: concrete STI base. Abstract **SalesContract** owns `customerId`; **PurchaseContract** owns `vendorId`. `channelId` is open-ended. Before upgrade, run `preflightCommercePartyLinks(db)` and repair linked base rows, stray parties, and wrong-branch links. See [README](README.md).\n- **WholesaleOrder**: B2B order. Conventional pairing — customer has `customerType: 'wholesale'`, NET-30/60 terms, delivered via wholesale-portal channel.\n- **ProductionOrder**: manufacturing equivalent of a PurchaseOrder — commission your factory to make finished goods. Consumes raw materials per BOM (`@happyvertical/smrt-manufacturing`) and produces SKU stock (`@happyvertical/smrt-inventory`).\n- **Cart**: transient order-in-progress. Same shape as Order; the application promotes the row from `_meta_type: Cart` to `_meta_type: Order` at checkout instead of copying data between tables.\n- **LicenseSale**: industry-neutral licensing primitive. Carries an *immutable* rights snapshot (`rightsMedium`, `rightsDistributionScope`, `rightsExclusivity`, `rightsDuration`, `rightsTerritory`, `rightsSublicensing`, `rightsDerivatives` — typed `Meta<T>` fields), licensee identity (`licenseeEmail`, optional `licenseeLegalEntity` / `licenseeJurisdiction`), and a signed-PDF reference (`pdfUrl`, `pdfHash`, optional `onChainHashRegistryRef`). Once saved at `ContractStatus.ACCEPTED`, the rights snapshot is frozen — mutating any of the seven rights fields and re-saving throws. The only legal transition out of ACCEPTED is `revoke()` (moves to CANCELLED without touching rights). Useful for stock media, music licensing, code-asset marketplaces, license keys, anywhere rights are sold for a fee.\n- **ContractLineItem**: items on contracts.\n- **Invoice**: status machine `DRAFT → SENT → VIEWED → PARTIAL → PAID` (also OVERDUE, CANCELLED, WRITTEN_OFF). `recognizeRevenue()` creates balanced AR journal entry (DR: Accounts Receivable, CR: Revenue, CR: Tax Payable).\n- **InvoiceLineItem**: fractional-quantity line items with safe minor-unit validation/recalculation on save; the existing-column migration is documented in [invoice quantity persistence](agents/invoice-quantity.md).\n- **Payment** / **PaymentAllocation**: tracks payments against invoices (status: see Gotchas). Carries optional backend-adapter fields for PaymentBackend-routed flows: `backendId` (rail adapter id — `base-usdc`, `btc`, `stripe`, distinct from `externalProvider` which names an accounting sync destination), `backendTxRef` (chain tx hash or gateway settlement id), `nativeAmount` / `nativeCurrency` (what actually arrived), `usdAtQuote` / `usdAtConfirmation` (drift accounting for volatile-currency rails). `Payment.usdDrift()` returns the confirmation - quote delta, or `0` when either side is unset.\n- **PaymentInstrument**: reusable saved payment method (\"card on file\"). Stores only provider references and non-sensitive display metadata (`providerCustomerId`, `providerPaymentMethodId`, brand / last4 / expiry), never raw card data. `isDefault` is domain-managed, not API-writable: `PaymentInstrumentCollection.setDefaultForCustomer(customerId, instrumentId)` validates the target and clears the customer's other defaults (one per customer).\n- **PaymentIntent**: short-lived pre-payment commitment with multi-option semantics. Locks a USD price for a fixed window (default 15 minutes) and lists one or more `PaymentOption`s describing different rails (`backendId`, `currency`, `payTo`, `nativeAmount`, optional `chain` / `memo` / `x402Capable` / `expiresAt`). First option to receive payment wins; the others are implicitly retired. State machine `awaiting_payment → paid → (issued | retired)` plus `expired` and `cancelled`. Mutate via dedicated `markPaid` / `markIssued` / `expire` / `cancel` / `retire` helpers — direct status assignment bypasses the invariant checks. Idempotency: see the natural-key Gotcha.\n- **Payout**: operator-to-supplier remittance. Distinct from Payment because direction, status machine, and chain semantics differ. Status machine `pending → sent → confirmed → failed` (failed is terminal but resettable via `resetFromFailed()` after fixing the underlying problem). References source `paymentId` (plain string) and destination `vendorId` (foreign key). Amount invariant `supplierNet === grossAmount - operatorFee` enforced exactly on save (integer minor units, no tolerance — #2401). `PayoutCollection.createFromPayment()` is the typical entry point; it pulls native amount / currency from the source Payment.\n- **Fulfillment** / **FulfillmentLineItem**: shipment/delivery tracking.\n\n## Recipes (#3590)\n\n`src/recipes.ts` declares four minimal `SmrtRecipe`s, emitted into the built\n`manifest.json` and `smrt-knowledge.json` `recipes`: `commerce.customers`\n(Customer), `commerce.vendors` (Vendor), `commerce.sales` (Order, requires\ncustomers), `commerce.purchases` (PurchaseOrder, requires vendors). Headers\nonly; line items, fulfilment, invoices, and payments are later recipes. Each\nhas user-facing help in `src/<name>.recipe.md` (#3591), and the fields those\nrecipes show carry `@field({ description })` text; keep both in plain\nlanguage for end users and update them when a recipe's fields change. See\n[core recipes](../core/agents/recipes.md).\n\nSee [historical issued sales](agents/historical-sales.md) for exact original source\nmoney, immutable source children and combined historical/live customer funds.\nSee [payment allocation integrity](agents/payment-allocations.md) for atomic splits,\nretry identity, parent corrections and supported dialects.\nSee [tax codes](agents/tax-codes.md) for tenant-owned rate components, default codes,\nand the standard codes every tenant gets.\nSee [document money persistence](agents/document-money.md) for the one money\nmodel: tax-code resolution, atomic aggregate writes, issued snapshots, and\nfrozen fields. Every Invoice and Contract money write needs a tenant. Host\nbootstrap is `ensureCommerceTenant(db, tenantId, { cookbook })`, which returns\n`{ tenantId }`. Money data written by an earlier version is refused with\n`COMMERCE_DATA_NEEDS_UPGRADE` until `smrt db:upgrade-commerce-money` converts\nit; see [money data upgrade](agents/money-upgrade.md).\nSee [Contract money persistence](agents/contract-money.md) for the Contract\naggregate and purchase recoverability.\n\n## Ledger Integration\n\n`@happyvertical/smrt-ledgers` is a regular dependency, loaded lazily via dynamic `import()` (never a static import) so the package graph stays a DAG (#1582). Invoice stores `arJournalId` and `revenueJournalId` as string references. `recognizeRevenue()` creates a balanced AR journal entry; `getArJournal()` returns null when no journal has been recognized yet.\n\n## Billing-period close (#3060)\n\n`src/billing/` closes periods from smrt-subscriptions charges; see the README\nfor usage.\n\n- **Port, not provider.** Period close, events, and credit checkout call only\n  the `BillingProvider` port (integer minor units). `stripe.ts` adapts\n  `@happyvertical/accounting`, which takes currency *major* units; convert with\n  `units.ts` and never hand-roll a Stripe call here. `units.ts` exponents are\n  an explicit ISO 4217 table matching the SDK's, never `Intl` display digits\n  (CLDR differs for IQD, MGA, … and drifts by ICU release). The SDK's\n  `*Minor` fields are already ISO minor units. Capabilities a rail may lack\n  (`chargeSavedPaymentMethod`, `createSetupCheckout`, `getCheckout`,\n  `setDefaultPaymentMethod`, `markInvoiceUncollectible`) are optional port\n  methods: detect them by presence, and keep additions optional (#3139).\n  `sendAndReconcile` refuses a provider invoice whose subtotal or total\n  disagrees with the local invoice.\n- **Replay safety is identity.** Close, invoice, line, payment, allocation,\n  and claim ids are `deterministicId()`s; `BillingLineSource` (conflict key\n  `source_type, source_id`) is the only double-billing guard, so never bill a\n  source without claiming it, and never widen that key. Each close step is\n  persisted before the next; `acquireCloseLease()` serializes workers. A\n  close that nets to a credit keeps its claims and ends `carried_forward`;\n  its subtotal is a `credit_carry_forward` source for the payer's next billed\n  close, which marks the carried close `completed`.\n- **Cycles and flat-plan coverage (#3116).** `cycles.ts` is the schedule\n  (pure; `BillingAccount.billingAnchorAt`, null = calendar months). A close\n  with no period closes each payer's `lastEndedBillingPeriod()`. Flat-plan\n  claims are the exception to \"id from the source\": their `sourceId` is\n  `<subscriptionId>:seq:<chainSequence>` and their `periodStart/End` is the\n  exact time they bill. `claimFlatWindow()` reads the last number, then the\n  coverage (claims ending after the window start), claims one gap as number\n  n + 1, and retries on conflict; reading in that order is what makes it\n  safe. That numbering, not the period, stops overlaps when schedules or\n  payers change — never claim a flat plan outside it, and keep both reads\n  bounded (no whole-history scans). Each numbered claim is its own invoice\n  line keyed `lineKey|periodStart` (a function of the claim alone, so a\n  resumed close rebuilds the same line ids). Proration is\n  `prorateMinorUnits()` (half up, BigInt) against the period's full cycle.\n- **System tables.** `BillingAccount`, `BillingPeriodClose`, and\n  `BillingLineSource` are not tenant-scoped and have no generated surface.\n  Collections stay unexported; models are root exports (#3082). Invoices,\n  payments, and journals are written in the seller's tenant; payer-owned\n  subscriptions and credit grants in a system context, only after\n  verification.\n- **Events** use smrt-jobs' delivery inbox under provider\n  `<name>-billing:<sellerTenantId>` and a provider-filtered\n  `ForgeProjectionRuntime`, so a runtime never claims another seller's\n  events; any other runtime sharing the inbox must pass `providers` too. Only\n  events this package acts on are stored: foreign checkouts are `ignored`,\n  and only `smrt_*` checkout metadata is kept; it is\n  HMAC-signed with the webhook secret at creation (empty values are omitted:\n  Stripe drops them), so another integration on the same account cannot forge\n  a credit purchase or a card setup; credit is granted only when the\n  collected total equals it plus provider tax. Checkout amounts come from the\n  re-read session (`getCheckout()`), never the Stripe event, whose amounts are\n  in Stripe's unit. Rotating the webhook secret strands in-flight checkouts\n  (up to 24 h). `observe()` re-reads provider state, so ordering never depends\n  on delivery order; the only provider writes in `observe()` are idempotent\n  (making a saved card the default). The standing hook runs inside the event\n  transaction and must be idempotent.\n- **Card on file and top-ups (#3139).** A saved card is the payer customer's\n  default `PaymentInstrument` (seller tenant, id from the provider method).\n  `autoChargeInvoices` bills such payers `charge_automatically`, decided once\n  and saved as `Invoice.collectionMethod` before the first push, which every\n  retry reuses (never recompute it: a lost push response would record a\n  method the provider was not asked for, #3190); activation follows `paid`, never send. An auto top-up attempt\n  is a `PENDING` `Payment` (`reference` `auto-top-up:<policyId>`, id from the\n  policy and `count()` of its attempts) inserted before the charge, so racing\n  evaluations derive one id and one charge; the charge key is derived from\n  that id. `applyAutoTopUpOutcome()` must run in a transaction and starts with\n  a conditional `UPDATE … WHERE status = 'pending'` row lock, so the hook and\n  the `payment` webhook settle once; the grant is keyed by the charge key.\n  Never settle an attempt outside that function. Taxed accounts are charged\n  with provider tax by default (#3194): the attempt row holds the credit\n  (the charge subtotal), the tax is journaled to tax payable at settlement,\n  and the attempt's tax decision is recorded in its `notes` so a re-drive\n  repeats the same charge request (the provider refuses a key reused with\n  different tax). `claimAttempt()` is the only place that decides a\n  skip and reports it (`onAutoTopUpSkipped`); `cardOnFile()` and period close\n  use `defaultCardInstrument()` — never copy that predicate. A provider write-off moves the local invoice to\n  `WRITTEN_OFF` (a later payment, by card or on a rail (#3188), is recorded\n  and reinstates the payer; the status stays, so \"paid in full\" for a\n  written-off invoice is read from its allocations).\n- **Billing invoices are money-model invoices.** The provider taxes them\n  (`providerTaxAmount`, server-managed, not API-writable, added to line tax),\n  so every billing line is an explicit `taxMode: 'override'` to the seller's\n  `out-of-scope` code. Charges are written before credits so the running\n  subtotal never goes negative, and provider tax is written in the save that\n  issues the invoice. Revenue posting is idempotent. `ledger.bookCurrency` is\n  required (ISO 4217, validated by `BillingRuntime`) and must equal the\n  billing currency. `toAccountingInput({ mapping })` emits major units.\n- **Payment rails (#3138).** A runtime has one issuing `provider` and any\n  number of `paymentProviders` (unique names, one inbox namespace each; a\n  provider with `capabilities.issuesInvoices === false` can never issue).\n  `observe()` resolves the provider from the delivery namespace, never the\n  payload. Crypto rails implement the port over `@happyvertical/payments`'\n  `CryptoCheckoutGateway`; never call BTCPay (or any gateway) from here.\n  Settlement is decided by the pure `decideAttempt()` from gateway state and\n  `paymentPolicy` — the gateway's `settled` is authoritative and nothing here\n  counts confirmations. A `BillingPaymentAttempt` (`(provider, checkout_id)`\n  deterministic id) records every state and settles once; grants and payments\n  are keyed by checkout id. Invoice payments close the issuer's invoice out of\n  band in `observe()` (idempotent) before `project()` records the payment, and\n  `settlePaidInvoice` skips (records nothing for) a `paidOutOfBand` invoice\n  the rail latched with `outOfBandRequestedAt`; other out-of-band closes are\n  recorded as `OTHER` payments. Rails never save cards or charge tax: a taxed\n  credit purchase on a rail needs an explicit `automaticTax: false`. Exceptions are flags for operators;\n  nothing reverses or refunds automatically.\n- **Known limits**: write-offs post no bad-debt journal (AR stays until paid\n  or journaled by an operator); discounts still reach Stripe as negative lines (the SDK's\n  line `discount` would change the lines a replayed push reconciles, so it\n  needs its own migration); `RetailCharge` has no adjustment ledger. Flat\n  plans are monthly, in arrears; plan changes are not prorated (#3119).\n\n## Cross-Package References\n\n- `customerId` → `@foreignKey('Customer')` (hard reference within package)\n- `vendorId` → `@foreignKey('Vendor')` on PurchaseContract only\n- `profileId` → plain string to smrt-profiles\n- `arJournalId`, `revenueJournalId` → plain string to smrt-ledgers\n- `skuId` (on `PaymentIntent`, `LicenseSale`) → plain string to smrt-products\n- `paymentId` (on `PaymentIntent`, `Payout`, `LicenseSale`) → plain string to `Payment` (same package, but kept as plain string for cross-model consistency)\n- `vendorId` on `Payout` → `@foreignKey(Vendor)` (hard reference within package)\n- Billing records reference tenants with `@crossPackageRef('@happyvertical/smrt-users:Tenant')` and charges, plan periods, and adjustments by plain `sourceId`\n\n## Gotchas\n\n- **Optional tenancy**: all models `@TenantScoped({ mode: 'optional' })` + nullable tenantId\n- **Money units and arithmetic**: money fields use signed integer minor units; rates and quantities remain decimal where their contracts require them. Exact rounding, tax-code resolution, safe-integer validation, and journal units are defined in the [commercial money model](agents/money-model.md) and [money calculator](agents/money-calculator.md). Do not reintroduce floating-point tolerances on money paths.\n- **Money documents need a tenant**: models are optionally tenant-scoped, but every Invoice and Contract money write requires one (`MoneyValidationError` `INVALID_MONEY_INPUT`, `Commerce money documents require a tenant`).\n- **Earlier-version money data is refused**: never add a read or conversion path for it. Detection and the one-shot upgrade are in [money data upgrade](agents/money-upgrade.md).\n- **Book currency is required**: `recognizeRevenue()` and `cancelWithRevenueReversal()` take a required `bookCurrency`, which must equal the invoice currency.\n- **Asset-native amounts stay outside line rescales**: `Payment.nativeAmount` and `PaymentIntent.paymentOptions[].nativeAmount` are per-asset values identified by `nativeCurrency`; normalize each asset to its own minor unit before any type conversion, and never apply the commerce ×100 line-money rescale to them.\n- **Invoice controls payment status**: not the Payment model — use `Invoice.updatePaymentStatus()`\n- **Tax comes from tax codes**: the server resolves each line's code and computes line tax and header totals; client totals and a line's stored `taxRate` are never inputs\n- **Profile linking**: separate `ProfileCollection.create()` needed to fetch actual Profile object\n- **PaymentIntent natural key**: `conflictColumns: ['tenant_id', 'offering_ref', 'licensee_email', 'idempotency_key']` — a retried `create` with the same tuple upserts the existing row. Use `PaymentIntentCollection.getOrCreateByIdempotencyKey()` to branch on `{ intent, created }`. Empty natural-key inputs (e.g. blank `idempotencyKey`) disable dedup by design.\n- **Payout state-machine guards**: `markSent` requires a non-empty `backendTxRef`; `markConfirmed` only valid from `SENT`; `markFailed` only valid from `PENDING` / `SENT` (a confirmed payout can't fail — that path is a refund). `resetFromFailed()` is the dedicated escape hatch from `FAILED` back to `PENDING` after an operator fixes the underlying problem; it clears `backendTxRef` so the next attempt picks up a fresh one.\n- **LicenseSale immutability**: rights snapshot freezes on save-with-status-ACCEPTED. The captured snapshot lives in a module-scoped `WeakMap<LicenseSale, string>` so it doesn't interact with the schema or round-trip through `_meta_data`. Drafts (status != ACCEPTED) remain mutable. To \"change\" an issued license: `revoke()` it, then issue a new `LicenseSale` row.\n- **Vendor.payoutAddresses normalization**: the constructor accepts either a `Record<string, string>` or a pre-serialized JSON string. `initialize()` re-normalizes after the framework's option-override pass; `save()` re-normalizes defensively against direct field assignment. Non-string values inside the input map are silently dropped to preserve the typed invariant downstream.\n\n## Commercial UI\n\n`CustomerSelect`/`VendorSelect` are the registered selectors for Customer and\nVendor (`selects` in `src/ui.ts`); models carry `ui.widget` / `ui.format` hints. See\n[customer/vendor UI](agents/customer-vendor-ui.md#selectors-3602).\n\nSee [commercial UI composition](agents/commercial-ui.md) for native form recovery, amount compatibility and backend ownership. Package-owned guides under `agents/` ship with the package.\n\n## Quote and estimate UI\n\n`src/svelte/quote-types.ts` separates unparsed draft strings from explicit\nminor-unit revision DTOs. Native row submitters, caller-owned retry identity and\nextension conventions are documented in [agents/quote-ui.md](agents/quote-ui.md).\n\n## Purchasing UI\n\n`PurchaseOrderEditor` preserves allocation IDs and explicit zeroes, including\nretained reduction rows; the server validates review fingerprints before recording.\nSee [agents/purchasing-ui.md](agents/purchasing-ui.md) for caller responsibilities.\n\n## Exact cost billing\n\nPure signed cost billing and explicit tax rounding are available through the\nindependent `cost-billing` subpath; see [contract](agents/cost-billing.md).\n\nSee [contract billing schedules](agents/contract-billing-schedules.md) for exact\napproved milestone capacity, immutable amendments and atomic canonical invoice issue.\n\n## Customer funds (#4079)\n\nSee [customer advances](agents/customer-funds.md) for explicitly configured\nunapplied-AR/deposit-liability receipts, conserved application/refund capacity,\nreal liability reclassification, final-invoice attestation and mutation guards.\nUse the public commands; `Payment.customerFundsJson` is command-owned.\n\nSee [observed purchase prices](agents/observed-purchase-prices.md) for incomplete\noriginal supplier prices, explicit unknown totals and reviewed completion.\nSee [received sales agreement money](agents/received-sales-contract-money.md) for\nexact complete source Order/Agreement evidence without synthetic lines or tax recognition.\n",
   "moduleDocs": [
     {
       "path": "agents/customer-vendor-ui.md",
@@ -19729,17 +21454,22 @@
     {
       "path": "README.md",
       "module": "README",
-      "content": "# @happyvertical/smrt-commerce\n\nCommerce models for the s-m-r-t framework. Covers customers, vendors, contracts (10 STI types), invoices with ledger integration, payments, and fulfillment tracking.\n\n## Installation\n\n```bash\npnpm add @happyvertical/smrt-commerce\n```\n\n## Usage\n\n```typescript\nimport { withTenant } from '@happyvertical/smrt-tenancy';\nimport {\n  CustomerCollection,\n  ContractCollection,\n  InvoiceCollection,\n  InvoiceLineItemCollection,\n  PaymentCollection,\n  PaymentMethod,\n  ensureCommerceTenant,\n} from '@happyvertical/smrt-commerce';\n\n// Once per tenant, after the host creates it: tax settings and standard codes.\nawait ensureCommerceTenant(db, tenantId);\n\n// Money documents (invoices, contracts, and their lines) belong to a tenant.\nawait withTenant({ tenantId }, async () => {\n  // Create a customer linked to a profile\n  const customers = await CustomerCollection.create({ db });\n  const customer = await customers.create({\n    profileId: 'profile-uuid',\n    creditLimit: 1000000, // $10,000.00 — money is integer minor units\n    paymentTerms: 'Net 30',\n  });\n\n  // Create an order (STI contract type)\n  const contracts = await ContractCollection.create({ db });\n  const order = await contracts.create({\n    _meta_type: 'Order',\n    customerId: customer.id,\n    currency: 'CAD',\n  });\n\n  // Create an invoice. The server resolves each line's tax code and computes\n  // line tax and the header totals; header amounts are never inputs.\n  const invoices = await InvoiceCollection.create({ db });\n  const invoice = await invoices.create({\n    customerId: customer.id,\n    contractId: order.id,\n    invoiceNumber: await invoices.generateInvoiceNumber(),\n    currency: 'CAD',\n  });\n  const lines = await InvoiceLineItemCollection.create({ db });\n  await lines.create({\n    invoiceId: invoice.id,\n    description: 'Consulting',\n    quantity: 10,\n    unitPrice: 10000, // $100.00\n  });\n\n  // Issuing freezes the money snapshot; then recognize revenue (creates a\n  // balanced journal in smrt-ledgers from the frozen facts).\n  const issued = await invoices.get({ id: invoice.id }, { cache: false });\n  issued.markSent();\n  await issued.save();\n  await issued.recognizeRevenue({\n    arAccountId: 'ar-account-id',\n    revenueAccountId: 'revenue-account-id',\n    taxAccountId: 'tax-account-id',\n    bookCurrency: 'CAD', // must equal the invoice currency\n  });\n\n  // Record a payment with ledger integration\n  const payments = await PaymentCollection.create({ db });\n  const payment = await payments.create({\n    contractId: order.id,\n    customerId: customer.id,\n    amount: issued.totalAmount,\n    method: PaymentMethod.CREDIT_CARD,\n  });\n  await payment.recordPayment({\n    ledgerId: 'ledger-id',\n    receivablesAccountId: 'ar-account-id',\n    cashAccountId: 'bank-account-id',\n  });\n});\n```\n\n## Commercial money calculator\n\nThe public `/money` entry is a pure calculator for line amounts, discounts,\ncomponent tax, document rounding, and totals. It consumes and returns integer\nminor-unit money values; tax and discount percentages are exact text (`'5'`\nmeans 5%). It does not persist or load documents.\n\n```ts\nimport { calculateMoneyDocument } from '@happyvertical/smrt-commerce/money';\n\nconst totals = calculateMoneyDocument({\n  currency: 'CAD',\n  lineAmountType: 'exclusive',\n  roundingScope: 'line',\n  lines: [{\n    id: 'consulting', quantity: 1, unitPrice: 10000,\n    discount: { kind: 'none' },\n    taxCode: {\n      id: 'gst', kind: 'taxable',\n      components: [{ taxComponentId: 'gst', percent: '5', compound: false }],\n    },\n  }],\n});\n```\n\n`resolveLineTaxCode()` resolves caller-loaded codes without I/O, and the\nSvelte `InvoiceEditor` renders the money controls from its required `money`\nprop. Frozen editor documents render a supplied stored snapshot without\nrecalculation. See the [commerce money calculator guide](../../docs/content/commerce-money.md)\nfor pricing modes, rounding, input and result types, the native-form editor\ncontract, and the boundaries this package does not define.\n\n### Tenant tax catalogue and defaults\n\nThe package root also exports tenant-scoped `TaxComponent`, `TaxCode`, and\n`TaxSettings` models and their collections. Components hold exact percentage\nrates and optional liability accounts; codes combine compatible components; the\none settings row per tenant supplies sales/purchase defaults, amount mode,\nrounding scope, and labelled registration numbers. A referenced component rate\nis immutable: archive it and create a replacement for a rate change.\n\n`ensureTenantTaxCodes(db, tenantId)` idempotently creates the standard\nnon-taxable codes, `exempt`, `zero-rated`, and `out-of-scope`\n(`STANDARD_TAX_CODES`). `applyTaxCodeExamplePack(db, tenantId)` installs illustrative\nregional examples for review, and `applyCommerceCookbookSettings(db, tenantId,\ncookbook)` explicitly materializes a validated cookbook's defaults after schema\nsetup and authentication establish the tenant. See the [commerce money\ncalculator guide](../../docs/content/commerce-money.md#tenant-tax-catalogue) for\nthe supported kinds, seed behavior, and cookbook rate units.\n\n### Persisted Invoice money\n\nCommerce has one money model. Tax codes resolve each line's tax: the line's\noverride, else `exempt` for an exempt customer, else the product's code, the\ncustomer's code, then the tenant default. The server computes line\n`taxAmount` and the header totals and ignores any client total. Every Invoice\nand Contract money write needs a tenant; without one it fails with\n`MoneyValidationError` `INVALID_MONEY_INPUT`.\n`ensureCommerceTenant(db, tenantId, { cookbook })` is the one bootstrap call a\nhost makes after creating a tenant. It seeds the tenant's tax settings, the\nstandard codes, and the cookbook's defaults, and returns `{ tenantId }`.\n\nIssuing an Invoice (leaving `DRAFT`) or assigning `arJournalId` freezes its\nmoney snapshot. Header and line money changes then fail with `FROZEN_DOCUMENT`,\nwhile later lifecycle and payment updates retain the snapshot. Provider tax\nstays separate in `providerTaxAmount` and contributes to the Invoice headers\nwithout creating an application tax code.\n`InvoiceLineItemCollection.getTotalForInvoice()` sums line amounts for\ncompatibility; use persisted `Invoice.totalAmount` for the amount due.\n`recognizeRevenue()` and `cancelWithRevenueReversal()` require a `bookCurrency`\nequal to the invoice currency, and `toAccountingInput({ mapping })` requires\nexplicit QuickBooks realm mapping. The\n[commerce money calculator guide](../../docs/content/commerce-money.md#persisted-invoice-money)\nand [document-money contract](agents/document-money.md) cover persisted Invoice\nsemantics, credits, refunds, and posting. The materialized Invoice tax-report\ndescriptor and tenant-safe drilldown are documented in\n[tax-summary contract](agents/tax-summary.md). Contract money persistence,\nPurchaseContract tax contributors, and the materialized tax-summary host and\ndrilldown are available. Applications opt in by registering\n`createTaxSummaryMaterializedReportHost()` in their server-only report-host\nregistry; the route binds the authenticated tenant and read permission. See the\ntax-summary contract for registration details.\n\n### Upgrading money data from an earlier version\n\nCommerce refuses money data written by an earlier version with\n`COMMERCE_DATA_NEEDS_UPGRADE` instead of reading it. That is a schema that\nstill has the earlier money columns or the `commerce_money_migration_documents` table,\nan invoice or contract without a tenant, or a tenant with invoices or contracts but no tax settings row or with\ndocuments in the earlier format. `smrt db:status`\nreports it, so `smrt app doctor` reports `migration-required`. Run the normal\nschema migration, then upgrade once:\n\n```sh\nsmrt db:upgrade-commerce-money --check   # report only\nsmrt db:upgrade-commerce-money           # every tenant\n```\n\nEach tenant converts in its own transaction. Stored rates become tax codes,\nissued documents keep every stored total, and drafts are recomputed. The\nearlier columns are dropped once no tenant needs the upgrade. See\n[money data upgrade](agents/money-upgrade.md) and the\n[CLI guide](../cli/agents/commerce-money-upgrade.md).\n\n## API\n\n### Models\n\n#### Supplier quotations\n\n`SupplierQuote` extends `PurchaseContract`, requires `vendorId`, and has\n`ContractType.SUPPLIER_QUOTE`. Create it through `PurchaseContractCollection`\n(or `ContractCollection`) with `_meta_type:\n'@happyvertical/smrt-commerce:SupplierQuote'`. It inherits `expiryDate`,\n`reference`, `notes`, and `terms`; it has no customer relationship. Purchase\nbranch reads include quotes and sales branch reads exclude them.\n\nKeep received quote revisions and shared quote identity in your application.\nAwarding a quote creates a separate `PurchaseOrder`; accepting or saving a\nquote never converts its identity into an order. Quotes use purchase-side\nmoney calculation and frozen snapshots, but never contribute incurred purchase\ntax to reports, regardless of status. Existing Estimate and PurchaseOrder\nreport eligibility is unchanged.\n\n#### Upgrading contract parties (#3898)\n\n`Contract` no longer declares `customerId` or `vendorId`. Narrow a contract to\n`SalesContract` to read `customerId`, or to `PurchaseContract` to read `vendorId`.\nThe existing leaf qualified names and the `contracts` table stay the same; a\n`db:migrate --dry-run` against a v0.55.19 schema reports no DDL changes on\nSQLite or PostgreSQL. Sales leaves no longer accept `vendorId`; purchase leaves\nno longer accept `customerId`. `Order`, `Estimate`, `Agreement`, `Lease`, and\n`WholesaleOrder` require a customer on save. `PurchaseOrder` and `SupplierQuote`\nrequire a vendor.\n`Cart`, `LicenseSale`, and `ProductionOrder` retain optional parties on their side.\n\nBefore upgrading existing data, run the read-only\n`preflightCommercePartyLinks(db)` and inspect its stray party links, missing\nrequired parties, base-typed rows, discriminator mismatches, and invalid\ndocument references. Its `unqualifiedDiscriminatorRows` lists legacy simple\n`_meta_type` values such as `Order` and `PurchaseOrder`; retype them to the\nqualified class name before upgrading, since branch collections cannot read\nthem. The report checks invoice, payment, fulfillment, ad group,\nand expense links when those tables exist. A linked base-typed or wrong-branch\ncontract blocks the next save of its document even when the link is unchanged.\nRegistered custom descendants of either contract branch are accepted in link\nchecks; load those model classes before running the preflight.\nTenant-owned documents linked to global or other-tenant contracts are also\nreported because the save-time lookup is tenant-scoped. Retype the contract to\nthe correct leaf, assign it to the document's tenant, or repair the link before\ndeployment. The deprecated `ContractCollection` party finders now return the\nappropriate branch\nonly, so retype legacy base rows with party links before relying on those\nfinders. Clear stray party columns and fill required parties before deploying\nwriters that save affected rows. Missing required parties remain readable but\nfail their next save. Regenerate cached manifests, planner catalogs, and\ngenerated screens after upgrading.\nThis preflight never edits rows; an operator chooses the data correction.\n\n| Export | Description |\n|--------|------------|\n| `Customer` | Customer record with creditLimit, paymentTerms, tax exemption, addresses, contacts |\n| `Vendor` | Vendor/supplier with leadTimeDays, minimumOrderAmount, currency, contacts |\n| `Contract` | STI base class for all commercial agreements |\n| `SalesContract` | Abstract customer-side Contract branch; owns `customerId` |\n| `PurchaseContract` | Abstract supplier-side Contract branch; owns `vendorId` |\n| `Estimate` | Quote or proposal sent to a customer |\n| `Order` | Customer purchase order |\n| `Lease` | Rental or lease agreement |\n| `Agreement` | Service or maintenance agreement |\n| `SupplierQuote` | Quotation received from a vendor; distinct from an awarded purchase order |\n| `PurchaseOrder` | Order sent to a vendor/supplier |\n| `ContractLineItem` | Line item within a contract |\n| `Invoice` | Billing document with status lifecycle and ledger integration |\n| `InvoiceLineItem` | Individual invoice line item |\n| `Payment` | Payment record with method, status, and optional ledger journal |\n| `PaymentAllocation` | Payment-to-invoice allocation |\n| `Fulfillment` | Shipment/delivery tracking with carrier and address |\n| `FulfillmentLineItem` | Individual fulfillment line item |\n| `BillingAccount` | A payer's account with a seller: customer, provider customer, terms, standing |\n| `BillingPeriodClose` | One payer's invoice for one period and currency; also the billing job target |\n| `BillingLineSource` | The claim that a charge or plan period is billed on exactly one close |\n\n### Collections\n\n`CustomerCollection`, `VendorCollection`, `ContractCollection`, `SalesContractCollection`, `PurchaseContractCollection`, `InvoiceCollection`, `InvoiceLineItemCollection`, `PaymentCollection`, `PaymentAllocationCollection`, `FulfillmentCollection`\n\n`PaymentAllocationCollection.allocatePayment()` splits a payment across invoices\nin one transaction using stable allocation IDs for retries. Direct allocation\nsaves also enforce matching owners, customers and currencies and both balance\ncaps. Read [payment allocation integrity](agents/payment-allocations.md) for\nreplay, parent revision refresh and compatibility requirements.\n\n\n### Enums\n\n| Export | Values |\n|--------|--------|\n| `ContractType` | `estimate`, `order`, `lease`, `agreement`, `supplier_quote`, `purchase_order`, `wholesale_order`, `production_order`, `cart`, `license_sale` |\n| `ContractStatus` | `draft`, `sent`, `accepted`, `declined`, `completed`, `cancelled` |\n| `CustomerStatus` | `active`, `inactive`, `suspended` |\n| `VendorStatus` | `active`, `inactive`, `suspended` |\n| `InvoiceStatus` | `draft`, `sent`, `viewed`, `partial`, `paid`, `overdue`, `cancelled`, `written_off` |\n| `PaymentMethod` | `cash`, `check`, `credit_card`, `bank_transfer`, `crypto`, `other` |\n| `PaymentStatus` | `pending`, `completed`, `failed`, `refunded`, `cancelled` |\n| `FulfillmentStatus` | `pending`, `processing`, `shipped`, `delivered`, `cancelled` |\n| `FulfillmentType` | `shipment`, `delivery`, `pickup`, `digital`, `service` |\n\n### Types and Constants\n\n| Export | Description |\n|--------|------------|\n| `Address` | Shared address interface (street1, street2, city, state, postalCode, country) |\n| `RecognizeRevenueOptions` | Account IDs for invoice revenue recognition |\n| `RecordPaymentOptions` | Ledger and account IDs for payment recording |\n| `InvoiceNumberOptions` | Options for `generateInvoiceNumber()` (prefix, format) |\n| `UNPAID_STATUSES` | Array of invoice statuses considered unpaid (sent, viewed, partial, overdue) |\n| `COMMERCE_MODULE_META` | UI module metadata |\n| `COMMERCE_UI_SLOTS` | UI slot definitions |\n\n### Ledger Integration\n\nInvoice and Payment integrate with `@happyvertical/smrt-ledgers` via dynamic import (optional dependency). Invoice stores `arJournalId` and `revenueJournalId` as plain string references to ledger journals. `recognizeRevenue()` creates a balanced AR entry (DR: Accounts Receivable, CR: Revenue, CR: Tax Payable). `recordPayment()` creates a balanced cash receipt entry (DR: Cash, CR: Accounts Receivable). Both methods return null or throw if the ledgers package is not installed.\n\n`Payment.recordPayment()` claims the payment revision and commits the journal,\nentries, and completed payment in one database transaction. A failed completion\nrolls back the posting and restores the instance's settlement fields for retry.\nThe claimed persisted status is authoritative even if a caller locally resets\nstatus or marks the instance failed without saving. Concurrent or stale instances\nfail instead of posting twice; reload the payment\nand retry only if it is still pending. An already completed payment retains the\n`Payment already recorded` error. A caller's enclosing transaction remains the\nowner: if it rolls back after settlement returns, reload the payment before retry.\nThese guarantees cover new postings, not orphaned journals written by older\nversions. The returned journal uses the caller's database executor.\n\n### Cross-Package References\n\nCustomer and Vendor link to `@happyvertical/smrt-profiles` via plain `profileId` string. Invoice and Payment reference `@happyvertical/smrt-ledgers` journals via plain string IDs (`arJournalId`, `revenueJournalId`, `journalId`). All models use `@TenantScoped({ mode: 'optional' })` with nullable `tenantId`.\n\n## Billing-period close\n\n`BillingRuntime` turns approved `@happyvertical/smrt-subscriptions` charges into\ninvoices for each billing owner, pushes them to a payment provider with\nprovider-calculated tax, posts revenue to the ledger, and applies the\nprovider's webhook events. Every provider call goes through\n`@happyvertical/accounting`; `createStripeBillingProvider()` adapts its Stripe\nprovider to the `BillingProvider` port. Money crossing the port is integer\nminor units.\n\n```ts\nimport { getAccountingProvider } from '@happyvertical/accounting';\nimport { SpendingPolicyEvaluator } from '@happyvertical/smrt-subscriptions';\nimport {\n  BillingRuntime,\n  createStripeBillingProvider,\n  enqueueBillingPeriodClose,\n  registerBillingRuntime,\n} from '@happyvertical/smrt-commerce';\n\nconst stripe = await getAccountingProvider({ type: 'stripe', secretKey });\nconst billing = await BillingRuntime.create({\n  db,\n  sellerTenantId: platformTenantId,\n  kind: 'provider', // or 'reseller' to bill a reseller's children\n  provider: createStripeBillingProvider({ stripe, webhookSecret }),\n  billingRelationships, // smrt-tenancy BillingRelationshipService\n  ledger: {\n    bookCurrency: 'USD', // ISO 4217; must equal the billing currency\n    arAccountId,\n    revenueAccountId,\n    taxAccountId,\n    cashAccountId,\n    prepaidCreditAccountId,\n  },\n  onPayerStanding: async ({ payerTenantId, standing, db }) => {\n    // suspend or reinstate the payer; runs in the event transaction\n  },\n});\n\n// One account per payer: its customer, tax location, and terms.\nawait billing.upsertAccount({\n  payerTenantId,\n  name: 'Network Co',\n  email: 'billing@example.test',\n  billingAddress: { country: 'CA', postalCode: 'T0L 0A0' },\n});\n\n// Optional: bill this payer from its activation date instead of calendar\n// months, prorating flat plans added mid-period (see \"Billing cycles\").\nawait billing.upsertAccount({\n  payerTenantId,\n  name: 'Network Co',\n  billingAnchorAt: activatedAt,\n  prorateFlatPlans: true,\n});\n\n// Close each payer's last ended period — safe to run on every schedule tick.\nregisterBillingRuntime('platform', billing);\nawait enqueueBillingPeriodClose({ runtime: 'platform' });\n\n// Webhook route: verify, enqueue, respond 2xx.\nconst intake = await billing.acceptWebhook(\n  rawBody,\n  request.headers.get('stripe-signature'),\n);\nif (intake.type?.endsWith(':unverified_credit_purchase')) {\n  // alert: a paid checkout claimed to buy credit but failed verification\n}\nawait billing.processEvents(); // or enqueueBillingEvents({ runtime: 'platform' })\n\n// Prepaid credit through provider checkout: tax is added on top when the\n// payer's account is taxed; `savePaymentMethod` keeps the card for top-ups.\nconst { url } = await billing.createCreditCheckout({\n  spendingPolicyId,\n  amount: 5000,\n  purchaseId: cartId,\n  savePaymentMethod: true,\n  successUrl,\n  cancelUrl,\n});\n\n// Card on file at signup: a setup checkout that charges nothing. Its\n// completion event makes the card the payer's default and adopts the billing\n// address collected at checkout as the tax location.\nconst setup = await billing.createCardSetupCheckout({\n  payerTenantId,\n  currency: 'CAD',\n  setupId: signupId,\n  successUrl,\n  cancelUrl,\n});\n\n// Automatic top-ups: charge the saved card when a balance would run out.\n// Accounts are taxed by default (`automaticTax`); a taxed account is charged\n// the credit plus provider-calculated tax (#3194).\nconst evaluator = await SpendingPolicyEvaluator.create({\n  db,\n  autoTopUp: billing.autoTopUpHook({ amount: () => 2500 }),\n});\n```\n\n- **What is billed.** A `provider` runtime bills `ClientCharge`s (and their\n  `BillingAdjustment`s) to the payer each charge names, plus monthly flat plans\n  it owns, to each subscriber's billing owner. A `reseller` runtime bills the\n  `RetailCharge`s its children owe it plus its own flat plans. Charges approved\n  before the period end are billed once, whatever period that is; flat plans\n  are billed in arrears for the payer's closed period (trials and\n  provider-managed subscriptions are skipped). One invoice per payer and\n  currency carries both kinds of lines.\n- **Replay safety.** Close, invoice, and line ids are derived from the payer,\n  currency, and period; each charge is claimed by exactly one close; the\n  provider invoice uses the close id as its idempotency key; and every step is\n  persisted before the next, so a retry resumes where it stopped. A lease stops\n  two workers advancing the same close. A close without a period also resumes\n  every unfinished close whose period has ended, even one the payer's current\n  schedule no longer produces (#3116). A payer whose charges net to a credit\n  gets no invoice; the credit is carried to its next invoice.\n- **Billing cycles (#3116).** A payer's periods follow its account's\n  `billingAnchorAt`. Unset (the default) they are UTC calendar months. Set,\n  they run monthly from the anchor at its UTC time of day; a day the month\n  lacks is clamped to its last day, always from the anchor itself (an anchor\n  on Jan 31 bills Jan 31 → Feb 28 → Mar 31). Before the anchor the schedule is\n  calendar months, and the anchor's own month ends at the anchor (a *stub*).\n  `closePeriod()` / `enqueueBillingPeriodClose()` with no period close each\n  payer's **last ended period on its own schedule**, so payers on different\n  anchors are closed by the same daily tick. An explicit\n  `{ periodStart, periodEnd }` closes that period for calendar payers (flat\n  plans only when it is a calendar month, as before) and for anchored payers\n  whose schedule has exactly that period. `billingPeriodFor(payer, at)` returns\n  a payer's current period; `billingPeriodContaining()`,\n  `lastEndedBillingPeriod()`, and `prorateMinorUnits()` are exported.\n- **Proration.** A flat plan is priced `price × billed time / cycle length`,\n  in integer minor units rounded half up (exact integer arithmetic; the\n  cycle is the period's own month, so February prorates over 28 or 29 days).\n  With `prorateFlatPlans` off (default) the billed time is the whole period\n  whenever the subscription was active in it and out of trial at its start —\n  the pre-#3116 behavior. With it on, the billed time is exactly the time the\n  subscription was active and out of trial: a subscription starting, leaving\n  trial, or canceled mid-period is billed pro rata. Proration happens before\n  the account's flat discount. Split into parts, prorated amounts can differ\n  from the full price by a minor unit.\n- **First period.** *Anchor at signup* (set `billingAnchorAt` to the\n  signup/activation instant): the first period is a full period from signup;\n  nothing before it is billed. *Bill from signup to the next anchor* (keep a\n  fixed anchor, or calendar months, and set `prorateFlatPlans`): the first\n  period is billed pro rata from signup. Items added later are prorated to the\n  payer's anchor when `prorateFlatPlans` is on and billed a full period\n  otherwise.\n- **Mid-period changes.** Billing is in arrears, so a cancellation needs no\n  credit: with proration the canceled period is billed up to `canceledAt`,\n  without it in full. A plan change is billed at the plan in effect at close\n  for the whole window (no plan-change proration yet, #3119), and a cancellation\n  back-dated into an already billed period is not credited — issue an\n  adjustment.\n- **No double billing across schedule changes.** Every flat-plan claim records\n  the exact time it bills, and a subscription's claims are numbered, so only\n  one worker can write the next claim and two can never claim the same time.\n  Moving an account from calendar months to an anchor, moving an anchor, or\n  moving a subscription to a payer on another schedule bills only time not yet\n  billed, prorated. For example, calendar months through February and then an\n  anchor on Mar 20 bills the Mar 1 → Mar 20 stub pro rata, then Mar 20 → Apr\n  20. Time around an already billed window is billed as separate lines, each\n  with its own service period. Stop workers running a pre-#3116 version\n  before relying on this: they claim flat plans outside the numbering.\n- **Service periods.** Each flat-plan invoice line carries its billed window\n  as `periodStart`/`periodEnd`, down to the provider port and on to Stripe's\n  invoice item `period`.\n- **Upgrading to #3116.** Additive schema only: `_smrt_billing_accounts` gains\n  `billing_anchor_at` (nullable) and `prorate_flat_plans` (default false), and\n  `_smrt_billing_line_sources` gains `chain_sequence` (default 0) and an index\n  on `(line_key, chain_sequence)`; run `smrt db:migrate`.\n  Existing accounts stay on calendar months, and claims written before the\n  upgrade (`<subscriptionId>:<periodStart>`, number 0) count as billed\n  coverage, so nothing is billed again after it.\n- **Tax** comes from the provider (Stripe Tax) using the account customer's\n  `defaultBillingAddress`; the invoice records it as `providerTaxAmount` in the\n  save that issues it. Billing invoices are ordinary money-model invoices in\n  the seller's tenant; period close seeds its standard codes if needed. Every\n  billing line is an explicit override to the seller's `out-of-scope` code, so\n  the seller's default code never taxes it a second time. Charges are written\n  before credits, so the running subtotal never goes negative. Revenue posting\n  uses `ledger.bookCurrency` and is idempotent.\n- **Events** are verified, stored in smrt-jobs' durable delivery inbox, and\n  applied against current provider state: paid invoices record a payment and\n  allocation; failures and overdue notices mark the payer `past_due` and its\n  flat-plan subscriptions `past_due`; an invoice written off at the provider\n  (`markInvoiceUncollectible(invoiceId)`, or in Stripe) is written off\n  locally and marks the payer `uncollectible` (no bad-debt journal is\n  posted; AR stays until it is paid or an operator journals it); payment\n  reinstates them, including a late payment of the written-off invoice. Dunning is the provider's.\n  Subscribe the webhook endpoint to `invoice.*`, `customer.subscription.*`,\n  `checkout.session.completed`, `checkout.session.async_payment_succeeded`,\n  and `payment_intent.*`.\n- **Prepaid credit** purchases credit a `period: 'balance'` spending policy\n  once per checkout session, paid by the policy's tenant or, for a delegated\n  balance, the parent that set it. Amounts are ISO 4217 minor units in any\n  currency the provider supports. When the payer's account is taxed\n  (`automaticTax`, not tax-exempt; override per call), provider tax is\n  charged on top and collected at checkout with the buyer's address: the\n  credit is the amount bought, the payment is the total collected, and the\n  tax is booked to the tax account. For a payer with a provider customer but\n  no local tax location, the address collected at checkout becomes its tax\n  location. `savePaymentMethod` requires a provider that can re-read the\n  checkout and set a default payment method, and is refused otherwise.\n- **Card on file (#3139).** `createCardSetupCheckout()` (or a credit purchase\n  with `savePaymentMethod`) saves the payer's card without charging it. On\n  completion the card becomes the provider customer's default and the\n  payer's default `PaymentInstrument`. When the checkout collected the billing\n  address (a taxed payer with no tax location), it becomes the payer's tax\n  location. `cardOnFile(payerTenantId)` returns `{ onFile, savedAt? }` from\n  the same check automatic charges use (a default card with the account's\n  provider customer), for \"card on file\" displays and signup activation;\n  the payer or a system context may call it (#3187).\n- **Automatically charged invoices.** With `autoChargeInvoices: true` on the\n  runtime, a payer with a default card is invoiced `charge_automatically`:\n  the provider charges the card after the invoice is sent, on its own\n  schedule, and retries failures. Each pushed invoice records the method in\n  `Invoice.collectionMethod` (`charge_automatically` or `send_invoice`; empty\n  for invoices pushed before #3190). Do not offer another payment rail on a\n  `charge_automatically` invoice the provider is still collecting.\n  Upgrading adds the `collection_method` column to `invoices` (run\n  `smrt db:migrate`). Activate service on the `current` standing\n  from the `paid` event, not on send; a failure marks the payer `past_due`.\n- **Automatic top-ups.** Taxed accounts (the default: `automaticTax` on, not\n  tax-exempt) are charged the credit plus provider-calculated tax (#3194):\n  the balance is credited the credit, the payment records the credit, and\n  the tax is booked to the tax account. `taxedAccounts: 'skip'` does not top\n  them up, and `'charge_untaxed'` charges them without tax. A taxed payer\n  without a tax location is not charged. A location Stripe rejects fails the\n  attempt with `failureCode: 'customer_tax_location_invalid'`\n  (`onAutoTopUpFailed`), and it is retried only after `retryAfterMs`. Pass\n  `onAutoTopUpSkipped` to learn when a needed top-up will not be charged\n  because of the payer's account. Its `reason` is `taxed_account`, `no_card`,\n  `no_account`, or `tax_location_invalid`, and more may be added. Use it, for\n  example, to ask the payer to top up by hand or to add a billing address; it is not called while a charge is processing, while a\n  declined card waits out `retryAfterMs`, or when the top-up is no longer\n  needed or `amount` declines it (#3189).\n  `billing.autoTopUpHook()` is the `autoTopUp` hook for\n  `SpendingPolicyEvaluator`: when a balance would run out it charges the\n  payer's saved card off-session (the delegating parent's, for a delegated\n  balance) and credits the balance only when the charge succeeds. A charge\n  still processing is credited from its `payment_intent.succeeded` event; a\n  decline or an authentication requirement credits nothing, closes the\n  attempt, and calls the runtime's `onAutoTopUpFailed` (ask the payer to\n  re-save their card with a setup checkout). One attempt runs per policy at a\n  time, retries of a declined card wait `retryAfterMs` (default one hour),\n  and the credit is granted exactly once however the outcome arrives.\n- **Product tax codes (#3194).** `taxCodes: { credit, invoice }` on the\n  runtime classifies prepaid credit (checkout purchases and taxed top-ups)\n  and billing-period invoice lines for Stripe Tax (`txcd_...`). Without it,\n  the Stripe account's default product tax code applies.\n- **Upgrading to #3194.** Requires `@happyvertical/accounting` 0.96 or later.\n  No schema change. Taxed accounts are now topped up with tax. To keep the\n  previous behaviour, pass `taxedAccounts: 'skip'`.\n- **Upgrading to #3139.** Requires `@happyvertical/accounting` 0.92 or later.\n  No schema change. Credit checkouts are now taxed for taxed accounts (pass\n  `automaticTax: false` to keep them untaxed), and Stripe customers are\n  created idempotently.\n\n### Payment rails: BTC and other crypto (#3138)\n\nA seller runtime can take payments on more than one **rail**. The issuing\n`provider` (Stripe) still issues, taxes, and emails every invoice; extra rails\nin `paymentProviders` let a payer choose, per payment, to pay an invoice or buy\nprepaid credit another way. The crypto rail runs short-lived, fiat-priced\ncheckouts through `@happyvertical/payments`' provider-neutral\n`CryptoCheckoutGateway` — BTCPay Server at launch — so another gateway can\nreplace BTCPay without changing this package or its consumers.\n\n```ts\nimport {\n  BillingRuntime,\n  createBtcPayBillingProvider,\n  createStripeBillingProvider,\n} from '@happyvertical/smrt-commerce';\n\nconst btcpay = createBtcPayBillingProvider({\n  baseUrl, apiKey, storeId,        // one BTCPay store per seller entity\n  webhookSecret, metadataSecret,   // from the host's secret store, by name\n  speedPolicy: 'LowMediumSpeed',   // settle after 2 confirmations (BTCPay offers 0/1/2/6)\n  rateSource: 'kraken',\n  minimumAmount: { CAD: 500, USD: 500 },\n});\nconst billing = await BillingRuntime.create({\n  db, sellerTenantId, kind: 'provider',\n  provider: createStripeBillingProvider({ stripe, webhookSecret }),\n  paymentProviders: [btcpay],\n  paymentPolicy: { latePaymentPolicy: 'review', refundBasis: 'original_native' },\n  billingRelationships,\n  ledger: { ...ledger, cryptoHoldingsAccountId, fxGainLossAccountId, feesAccountId },\n});\n\n// Prepaid credit or an issued invoice, paid with BTC:\nawait billing.createCreditCheckout({ ...purchase, provider: 'btcpay' });\nawait billing.createInvoicePayment({ invoiceId, provider: 'btcpay', purchaseId, successUrl, cancelUrl });\n\n// Webhook route for the rail (BTCPay signs with its own header):\nawait billing.acceptWebhook(rawBody, '', { provider: 'btcpay', headers: request.headers });\nawait billing.processEvents();\n```\n\n- **Refusals are typed (#3185).** `createInvoicePayment()` and\n  `createCreditCheckout()` throw `BillingPaymentRefusedError` for requests the\n  payer can correct, with a stable `code`: `not_found`, `not_payable`,\n  `payment_in_progress`, `nothing_due`, `invalid_amount`, `below_minimum`\n  (under the rail's `minimumAmount`), or `no_account`. Show its message as a\n  4xx; any other error is a server failure, and `TenantIsolationError` still\n  means the caller is not the payer. Treat an unknown code like\n  `not_payable`.\n- **Settlement is the gateway's.** Credit is granted and invoices are paid\n  only when the gateway reports `settled` under its own confirmation policy;\n  this package never counts confirmations. BTCPay offers 0, 1, 2 or 6\n  confirmations; the default is `LowMediumSpeed` (2 confirmations).\n- **Payment attempts.** Every rail checkout is a `BillingPaymentAttempt`\n  recording the locked fiat price, fiat and native amounts received, rate and\n  rate source, each payment's txid, rail and fee, a timeline of status changes,\n  and what settlement produced. `listPaymentAttempts()` feeds \"payment\n  confirming\" displays and operator queues; every filter applies before its\n  `limit` and `offset`, so paging through `{ unresolved: true }` lists every\n  open exception (flagged, not yet resolved) however old. `refreshPaymentAttempts()` is the polling\n  fallback for missed webhooks.\n- **Dunning pauses** for an invoice while a payment for it is confirming\n  (0-conf seen); if the payment then expires or is invalidated the payer's\n  standing is re-applied.\n- **Invoices paid on a rail** are closed at the issuer with\n  `markInvoicePaidOutOfBand` (Stripe `paid_out_of_band`), so Stripe stops\n  collecting; Stripe's own `paid` event then records nothing more.\n  `createInvoicePayment` refuses when the issuing provider cannot do that.\n  A written-off (uncollectible) invoice with an amount due can be paid on a\n  rail too, as it can by card at Stripe (#3188): the payment is recorded,\n  Stripe's invoice is closed out of band, and the payer returns to `current`;\n  the invoice keeps its `WRITTEN_OFF` status (its `amountPaid` shows the\n  recovery).\n- **Exceptions never auto-refund.** Underpaid, overpaid, late, manually marked\n  (at the gateway), invalidated-after-settlement, and paid-twice attempts are\n  flagged for an operator (`resolvePaymentAttempt`). Per-seller\n  `paymentPolicy` sets under/overpayment tolerances (basis points), late\n  payments (`review` | `accept`), manually marked checkouts, hold vs convert\n  (`conversionHandler`), and the refund basis.\n- **Ledger.** Receipts are booked at the locked fiat amount into\n  `cryptoHoldingsAccountId` (default `cashAccountId`); money received above\n  the price is booked as customer credit (prepaid-credit liability).\n  `recordManualRefund()` refunds from that excess first, then from purchased\n  credit (or an invoice payment kept as credit because the invoice was paid\n  elsewhere) — capped cumulatively, once per reference; an invoice payment\n  applied to its invoice is reversed at the issuer, not here.\n  `recordCryptoConversion()` posts a conversion with FX gain/loss.\n- **Upgrading.** Additive schema: `_smrt_billing_payment_attempts` (run\n  `smrt db:migrate`). A runtime without `paymentProviders` never reads it.\n- **One live payment per invoice.** The issuer's own `paid` event for an\n  invoice a rail closed out of band records nothing (the rail records it); an\n  out-of-band close made by someone else (wire, cheque) is recorded as an\n  `OTHER`-method payment; a real card payment made while a rail payment\n  confirms is recorded and the rail money is flagged `invoice_already_paid`.\n  An issuer close whose rail payment never settles is flagged\n  `out_of_band_without_settlement`: reopen the invoice at the issuer, then\n  `resolvePaymentAttempt()` it, after which a later out-of-band close is\n  recorded normally.\n- **Entities.** Each legal entity is its own seller runtime with its own\n  store, keys, and ledger. Inter-entity resale is ordinary reseller billing\n  between two sellers, payable on any rail the selling entity offers.\n\nSee [`AGENTS.md`](./AGENTS.md#billing-period-close-3060) for invariants and\nknown limits.\n\n## Dependencies\n\n- `@happyvertical/smrt-core` -- ORM and code generation\n- `@happyvertical/smrt-tenancy` -- multi-tenant scoping\n- `@happyvertical/smrt-subscriptions` -- charges, plans, and credit balances billed by period close\n- `@happyvertical/smrt-jobs` -- period-close jobs and the provider event inbox\n- `@happyvertical/accounting` -- payment-provider (Stripe) calls\n- `@happyvertical/smrt-types` -- shared type definitions\n- Peer: `@happyvertical/smrt-ledgers`, `@happyvertical/smrt-profiles`, `@happyvertical/smrt-svelte`\n\n## Contributor guide\n\nSee [`AGENTS.md`](./AGENTS.md) for package architecture, invariants, validation,\nand contributor guidance.\n\n## Pricing version UI\n\n`PricingVersionSummary` and `PricingVersionDecision` compose the quote revision\ncontract without adding a pricing ledger. Compare versions using\n`QuoteRevisionComparison`; the application owns every decision and native form\naction. See [pricing version presentation](agents/pricing-versions.md).\n\n## Commercial UI composition\n\nCustomer addresses and vendor/quote currencies use the shared localized code\nselectors while preserving native field names and rejected raw drafts. See\n[commercial UI contracts and backend boundaries](agents/commercial-ui.md) for\nnative forms, recovery, amount units and consumer adoption, plus the focused\n[customer/vendor](agents/customer-vendor-ui.md) and\n[quotation](agents/quote-ui.md) contracts for selector restrictions.\n\n## Customer and vendor contacts\n\n`Customer.contacts` and `Vendor.contacts` hold the people to reach at a party\n(`PartyContact`: `id`, `name`, `label`, `email`, `phone`, `address`) as a JSON\ncolumn; existing databases need `smrt db:migrate` for the new `contacts`\ncolumns. The form's contact rows are written with `savePartyContacts()`:\n\n```typescript\nimport {\n  applyPartyContactIntent,\n  PartyContactValidationError,\n  readPartyContactRows,\n  savePartyContacts,\n} from '@happyvertical/smrt-commerce';\n\nconst form = await request.formData();\n// Throws PartyContactPayloadError when the form's contactCount marker is absent\n// (block not rendered, or fieldNames differ), so a save never deletes by accident.\nconst rows = readPartyContactRows(form); // pass the form's fieldNames if overridden\nconst { contacts, handled } = applyPartyContactIntent(rows, String(form.get('intent')));\nif (handled) return { values: { ...values, contacts } }; // add/remove round trip, no save\ntry {\n  await savePartyContacts(vendors, vendorId, rows, { expectedTenantId });\n} catch (error) {\n  if (error instanceof PartyContactValidationError)\n    return fail(400, { values: { ...values, contacts: rows }, errors: { contacts: toMessages(error.errors) } });\n  throw error;\n}\n```\n\n`savePartyContacts` also accepts the `FormData` itself (with `fieldNames`) and\nreads it the same way. The rows replace the party's contacts: posted ids are kept, new rows get an\nid, unposted rows are removed, blank rows are dropped. See\n[customer/vendor UI](agents/customer-vendor-ui.md#contact-rows-3501).\n\n## Customer and vendor selectors\n\n`CustomerSelect` and `VendorSelect` from `@happyvertical/smrt-commerce/svelte`\nare searchable, field-sized pickers for a customer or vendor relation field.\nThey are registered in `COMMERCE_UI_SLOTS` with `selects:\n'@happyvertical/smrt-commerce:Customer'` / `':Vendor'`, so generic forms (via\n`findSelectorFor` over the manifest's `uiSelectors`) use them for any\n`@foreignKey` or `@crossPackageRef` field targeting those models.\n\nThey are presentation only. The caller owns the data: `search(query)` returns\nthe existing party DTOs (`CustomerDisplayData` / `VendorDisplayData`, whose\n`profile.name` is the label), and `resolve(id)` returns the record behind the\ncurrent value. Each row shows the profile name with status (and customer type).\nThe committed id, never the name, posts under `name`. Pass `onCreate` to offer a\n\"New customer\" / \"New vendor\" action; it receives the searched text, and a\nreturned record is selected.\n\n```svelte\n<CustomerSelect\n  name=\"customerId\"\n  bind:value={customerId}\n  search={(query) => customers.search(query)}\n  resolve={(id) => customers.byId(id)}\n  onCreate={(query) => openCustomerDialog(query)}\n/>\n```\n\nThe same models carry `@field({ ui: { widget } })` hints in the manifest:\n`textarea` on `Contract` (and subclass) `terms` and `notes`, `Customer`/`Vendor`\n`notes`, and `Invoice` notes and terms; `currency` (an ISO 4217 code picker) on\n`Contract`, `Vendor`, `Invoice` and `Payment` `currency`; `email`/`phone` on\n`Vendor.defaultContactEmail`/`defaultContactPhone`. See\n[customer and vendor selectors](agents/customer-vendor-ui.md#selectors-3602).\n\n## Invoice preparation UI\n\n`InvoiceEditor` from `@happyvertical/smrt-commerce/svelte` is the invoice form,\nbuilt on the commercial money model, v2, which is the only invoice money model.\nIt requires a `money` prop (`MoneyEditorProps`): a lossless draft with\ndescriptions, fractional quantities, unit prices, percentage or amount\ndiscounts and a tax code per line (inherited or overridden), plus the\nauthorized tax codes. Its previews run the same exact calculator the server\nuses, and the server re-resolves tax codes and recomputes every stored amount.\nAn issued document renders only its frozen stored snapshot.\n`InvoiceAllocationFields` and `InvoiceReview` add caller-owned sources and\napprovals. See [the editor contract](agents/invoice-preparation.md), the\n[line calculation helper](agents/invoice-calculations.md), and the\n[existing-database storage migration](agents/invoice-quantity.md).\n\n## Exact cost billing\n\nThe independent `@happyvertical/smrt-commerce/cost-billing` entry point provides\nexact signed reimbursement/fee calculations, ordered generic markup provenance,\nand explicit line or invoice tax rounding. Its opt-in ordered tax calculator\nsupports subset compounding with caller-selected signed invoice allocation.\nSee [the cost billing contract](agents/cost-billing.md).\nIt does not alter Invoice persistence, editor defaults or settlement behavior.\n\n### Purchase-order header editing\n\nImport `PurchaseOrderHeaderForm` from `@happyvertical/smrt-commerce/svelte` for a\nnative POST of vendor, reference, notes, expected date and ship-to fields. Pass\n`action`, `vendors` and raw `values`; return canonical field `errors` and the same\n`hiddenFields` after server validation. This header-only form leaves purchase\nallocations and totals unchanged. `PurchaseOrder` stores `expectedDate` and\n`shipTo` in existing STI metadata. See [the purchasing contract](agents/purchasing-ui.md#purchase-order-header)\nfor validation, retained values and transport details.\n"
+      "content": "# @happyvertical/smrt-commerce\n\nCommerce models for the s-m-r-t framework. Covers customers, vendors, contracts (10 STI types), invoices with ledger integration, payments, and fulfillment tracking.\n\n## Installation\n\n```bash\npnpm add @happyvertical/smrt-commerce\n```\n\n## Usage\n\n```typescript\nimport { withTenant } from '@happyvertical/smrt-tenancy';\nimport {\n  CustomerCollection,\n  ContractCollection,\n  InvoiceCollection,\n  InvoiceLineItemCollection,\n  PaymentCollection,\n  PaymentMethod,\n  ensureCommerceTenant,\n} from '@happyvertical/smrt-commerce';\n\n// Once per tenant, after the host creates it: tax settings and standard codes.\nawait ensureCommerceTenant(db, tenantId);\n\n// Money documents (invoices, contracts, and their lines) belong to a tenant.\nawait withTenant({ tenantId }, async () => {\n  // Create a customer linked to a profile\n  const customers = await CustomerCollection.create({ db });\n  const customer = await customers.create({\n    profileId: 'profile-uuid',\n    creditLimit: 1000000, // $10,000.00 — money is integer minor units\n    paymentTerms: 'Net 30',\n  });\n\n  // Create an order (STI contract type)\n  const contracts = await ContractCollection.create({ db });\n  const order = await contracts.create({\n    _meta_type: 'Order',\n    customerId: customer.id,\n    currency: 'CAD',\n  });\n\n  // Create an invoice. The server resolves each line's tax code and computes\n  // line tax and the header totals; header amounts are never inputs.\n  const invoices = await InvoiceCollection.create({ db });\n  const invoice = await invoices.create({\n    customerId: customer.id,\n    contractId: order.id,\n    invoiceNumber: await invoices.generateInvoiceNumber(),\n    currency: 'CAD',\n  });\n  const lines = await InvoiceLineItemCollection.create({ db });\n  await lines.create({\n    invoiceId: invoice.id,\n    description: 'Consulting',\n    quantity: 10,\n    unitPrice: 10000, // $100.00\n  });\n\n  // Issuing freezes the money snapshot; then recognize revenue (creates a\n  // balanced journal in smrt-ledgers from the frozen facts).\n  const issued = await invoices.get({ id: invoice.id }, { cache: false });\n  issued.markSent();\n  await issued.save();\n  await issued.recognizeRevenue({\n    arAccountId: 'ar-account-id',\n    revenueAccountId: 'revenue-account-id',\n    taxAccountId: 'tax-account-id',\n    bookCurrency: 'CAD', // must equal the invoice currency\n  });\n\n  // Record a payment with ledger integration\n  const payments = await PaymentCollection.create({ db });\n  const payment = await payments.create({\n    contractId: order.id,\n    customerId: customer.id,\n    amount: issued.totalAmount,\n    method: PaymentMethod.CREDIT_CARD,\n  });\n  await payment.recordPayment({\n    ledgerId: 'ledger-id',\n    receivablesAccountId: 'ar-account-id',\n    cashAccountId: 'bank-account-id',\n  });\n});\n```\n\n## Commercial money calculator\n\nThe public `/money` entry is a pure calculator for line amounts, discounts,\ncomponent tax, document rounding, and totals. It consumes and returns integer\nminor-unit money values; tax and discount percentages are exact text (`'5'`\nmeans 5%). It does not persist or load documents.\n\n```ts\nimport { calculateMoneyDocument } from '@happyvertical/smrt-commerce/money';\n\nconst totals = calculateMoneyDocument({\n  currency: 'CAD',\n  lineAmountType: 'exclusive',\n  roundingScope: 'line',\n  lines: [{\n    id: 'consulting', quantity: 1, unitPrice: 10000,\n    discount: { kind: 'none' },\n    taxCode: {\n      id: 'gst', kind: 'taxable',\n      components: [{ taxComponentId: 'gst', percent: '5', compound: false }],\n    },\n  }],\n});\n```\n\n`resolveLineTaxCode()` resolves caller-loaded codes without I/O, and the\nSvelte `InvoiceEditor` renders the money controls from its required `money`\nprop. Frozen editor documents render a supplied stored snapshot without\nrecalculation. See the [commerce money calculator guide](../../docs/content/commerce-money.md)\nfor pricing modes, rounding, input and result types, the native-form editor\ncontract, and the boundaries this package does not define.\n\n### Tenant tax catalogue and defaults\n\nThe package root also exports tenant-scoped `TaxComponent`, `TaxCode`, and\n`TaxSettings` models and their collections. Components hold exact percentage\nrates and optional liability accounts; codes combine compatible components; the\none settings row per tenant supplies sales/purchase defaults, amount mode,\nrounding scope, and labelled registration numbers. A referenced component rate\nis immutable: archive it and create a replacement for a rate change.\n\n`ensureTenantTaxCodes(db, tenantId)` idempotently creates the standard\nnon-taxable codes, `exempt`, `zero-rated`, and `out-of-scope`\n(`STANDARD_TAX_CODES`). `applyTaxCodeExamplePack(db, tenantId)` installs illustrative\nregional examples for review, and `applyCommerceCookbookSettings(db, tenantId,\ncookbook)` explicitly materializes a validated cookbook's defaults after schema\nsetup and authentication establish the tenant. See the [commerce money\ncalculator guide](../../docs/content/commerce-money.md#tenant-tax-catalogue) for\nthe supported kinds, seed behavior, and cookbook rate units.\n\n### Persisted Invoice money\n\nCommerce has one money model. Tax codes resolve each line's tax: the line's\noverride, else `exempt` for an exempt customer, else the product's code, the\ncustomer's code, then the tenant default. The server computes line\n`taxAmount` and the header totals and ignores any client total. Every Invoice\nand Contract money write needs a tenant; without one it fails with\n`MoneyValidationError` `INVALID_MONEY_INPUT`.\n`ensureCommerceTenant(db, tenantId, { cookbook })` is the one bootstrap call a\nhost makes after creating a tenant. It seeds the tenant's tax settings, the\nstandard codes, and the cookbook's defaults, and returns `{ tenantId }`.\n\nIssuing an Invoice (leaving `DRAFT`) or assigning `arJournalId` freezes its\nmoney snapshot. Header and line money changes then fail with `FROZEN_DOCUMENT`,\nwhile later lifecycle and payment updates retain the snapshot. Provider tax\nstays separate in `providerTaxAmount` and contributes to the Invoice headers\nwithout creating an application tax code.\n`InvoiceLineItemCollection.getTotalForInvoice()` sums line amounts for\ncompatibility; use persisted `Invoice.totalAmount` for the amount due.\n`recognizeRevenue()` and `cancelWithRevenueReversal()` require a `bookCurrency`\nequal to the invoice currency, and `toAccountingInput({ mapping })` requires\nexplicit QuickBooks realm mapping. The\n[commerce money calculator guide](../../docs/content/commerce-money.md#persisted-invoice-money)\nand [document-money contract](agents/document-money.md) cover persisted Invoice\nsemantics, credits, refunds, and posting. The materialized Invoice tax-report\ndescriptor and tenant-safe drilldown are documented in\n[tax-summary contract](agents/tax-summary.md). Contract money persistence,\nPurchaseContract tax contributors, and the materialized tax-summary host and\ndrilldown are available. Applications opt in by registering\n`createTaxSummaryMaterializedReportHost()` in their server-only report-host\nregistry; the route binds the authenticated tenant and read permission. See the\ntax-summary contract for registration details.\n\n### Upgrading money data from an earlier version\n\nCommerce refuses money data written by an earlier version with\n`COMMERCE_DATA_NEEDS_UPGRADE` instead of reading it. That is a schema that\nstill has the earlier money columns or the `commerce_money_migration_documents` table,\nan invoice or contract without a tenant, or a tenant with invoices or contracts but no tax settings row or with\ndocuments in the earlier format. `smrt db:status`\nreports it, so `smrt app doctor` reports `migration-required`. Run the normal\nschema migration, then upgrade once:\n\n```sh\nsmrt db:upgrade-commerce-money --check   # report only\nsmrt db:upgrade-commerce-money           # every tenant\n```\n\nEach tenant converts in its own transaction. Stored rates become tax codes,\nissued documents keep every stored total, and drafts are recomputed. The\nearlier columns are dropped once no tenant needs the upgrade. See\n[money data upgrade](agents/money-upgrade.md) and the\n[CLI guide](../cli/agents/commerce-money-upgrade.md).\n\n## API\n\n### Models\n\n#### Supplier quotations\n\n`SupplierQuote` extends `PurchaseContract`, requires `vendorId`, and has\n`ContractType.SUPPLIER_QUOTE`. Create it through `PurchaseContractCollection`\n(or `ContractCollection`) with `_meta_type:\n'@happyvertical/smrt-commerce:SupplierQuote'`. It inherits `expiryDate`,\n`reference`, `notes`, and `terms`; it has no customer relationship. Purchase\nbranch reads include quotes and sales branch reads exclude them.\n\nKeep received quote revisions and shared quote identity in your application.\nAwarding a quote creates a separate `PurchaseOrder`; accepting or saving a\nquote never converts its identity into an order. Quotes use purchase-side\nmoney calculation and frozen snapshots, but never contribute incurred purchase\ntax to reports, regardless of status. Existing Estimate and PurchaseOrder\nreport eligibility is unchanged.\n\n#### Upgrading contract parties (#3898)\n\n`Contract` no longer declares `customerId` or `vendorId`. Narrow a contract to\n`SalesContract` to read `customerId`, or to `PurchaseContract` to read `vendorId`.\nThe existing leaf qualified names and the `contracts` table stay the same; a\n`db:migrate --dry-run` against a v0.55.19 schema reports no DDL changes on\nSQLite or PostgreSQL. Sales leaves no longer accept `vendorId`; purchase leaves\nno longer accept `customerId`. `Order`, `Estimate`, `Agreement`, `Lease`, and\n`WholesaleOrder` require a customer on save. `PurchaseOrder` and `SupplierQuote`\nrequire a vendor.\n`Cart`, `LicenseSale`, and `ProductionOrder` retain optional parties on their side.\n\nBefore upgrading existing data, run the read-only\n`preflightCommercePartyLinks(db)` and inspect its stray party links, missing\nrequired parties, base-typed rows, discriminator mismatches, and invalid\ndocument references. Its `unqualifiedDiscriminatorRows` lists legacy simple\n`_meta_type` values such as `Order` and `PurchaseOrder`; retype them to the\nqualified class name before upgrading, since branch collections cannot read\nthem. The report checks invoice, payment, fulfillment, ad group,\nand expense links when those tables exist. A linked base-typed or wrong-branch\ncontract blocks the next save of its document even when the link is unchanged.\nRegistered custom descendants of either contract branch are accepted in link\nchecks; load those model classes before running the preflight.\nTenant-owned documents linked to global or other-tenant contracts are also\nreported because the save-time lookup is tenant-scoped. Retype the contract to\nthe correct leaf, assign it to the document's tenant, or repair the link before\ndeployment. The deprecated `ContractCollection` party finders now return the\nappropriate branch\nonly, so retype legacy base rows with party links before relying on those\nfinders. Clear stray party columns and fill required parties before deploying\nwriters that save affected rows. Missing required parties remain readable but\nfail their next save. Regenerate cached manifests, planner catalogs, and\ngenerated screens after upgrading.\nThis preflight never edits rows; an operator chooses the data correction.\n\n| Export | Description |\n|--------|------------|\n| `Customer` | Customer record with creditLimit, paymentTerms, tax exemption, addresses, contacts |\n| `Vendor` | Vendor/supplier with leadTimeDays, minimumOrderAmount, currency, contacts |\n| `Contract` | STI base class for all commercial agreements |\n| `SalesContract` | Abstract customer-side Contract branch; owns `customerId` |\n| `PurchaseContract` | Abstract supplier-side Contract branch; owns `vendorId` |\n| `Estimate` | Quote or proposal sent to a customer |\n| `Order` | Customer purchase order |\n| `Lease` | Rental or lease agreement |\n| `Agreement` | Service or maintenance agreement |\n| `SupplierQuote` | Quotation received from a vendor; distinct from an awarded purchase order |\n| `PurchaseOrder` | Order sent to a vendor/supplier |\n| `ContractLineItem` | Line item within a contract |\n| `Invoice` | Billing document with status lifecycle and ledger integration |\n| `InvoiceLineItem` | Individual invoice line item |\n| `Payment` | Payment record with method, status, and optional ledger journal |\n| `PaymentAllocation` | Payment-to-invoice allocation |\n| `Fulfillment` | Shipment/delivery tracking with carrier and address |\n| `FulfillmentLineItem` | Individual fulfillment line item |\n| `BillingAccount` | A payer's account with a seller: customer, provider customer, terms, standing |\n| `BillingPeriodClose` | One payer's invoice for one period and currency; also the billing job target |\n| `BillingLineSource` | The claim that a charge or plan period is billed on exactly one close |\n\n### Collections\n\n`CustomerCollection`, `VendorCollection`, `ContractCollection`, `SalesContractCollection`, `PurchaseContractCollection`, `InvoiceCollection`, `InvoiceLineItemCollection`, `PaymentCollection`, `PaymentAllocationCollection`, `FulfillmentCollection`\n\n`PaymentAllocationCollection.allocatePayment()` splits a payment across invoices\nin one transaction using stable allocation IDs for retries. Direct allocation\nsaves also enforce matching owners, customers and currencies and both balance\ncaps. Read [payment allocation integrity](agents/payment-allocations.md) for\nreplay, parent revision refresh and compatibility requirements.\n\n\n### Enums\n\n| Export | Values |\n|--------|--------|\n| `ContractType` | `estimate`, `order`, `lease`, `agreement`, `supplier_quote`, `purchase_order`, `wholesale_order`, `production_order`, `cart`, `license_sale` |\n| `ContractStatus` | `draft`, `sent`, `accepted`, `declined`, `completed`, `cancelled` |\n| `CustomerStatus` | `active`, `inactive`, `suspended` |\n| `VendorStatus` | `active`, `inactive`, `suspended` |\n| `InvoiceStatus` | `draft`, `sent`, `viewed`, `partial`, `paid`, `overdue`, `cancelled`, `written_off` |\n| `PaymentMethod` | `cash`, `check`, `credit_card`, `bank_transfer`, `crypto`, `other` |\n| `PaymentStatus` | `pending`, `completed`, `failed`, `refunded`, `cancelled` |\n| `FulfillmentStatus` | `pending`, `processing`, `shipped`, `delivered`, `cancelled` |\n| `FulfillmentType` | `shipment`, `delivery`, `pickup`, `digital`, `service` |\n\n### Types and Constants\n\n| Export | Description |\n|--------|------------|\n| `Address` | Shared address interface (street1, street2, city, state, postalCode, country) |\n| `RecognizeRevenueOptions` | Account IDs for invoice revenue recognition |\n| `RecordPaymentOptions` | Ledger and account IDs for payment recording |\n| `InvoiceNumberOptions` | Options for `generateInvoiceNumber()` (prefix, format) |\n| `UNPAID_STATUSES` | Array of invoice statuses considered unpaid (sent, viewed, partial, overdue) |\n| `COMMERCE_MODULE_META` | UI module metadata |\n| `COMMERCE_UI_SLOTS` | UI slot definitions |\n\n### Ledger Integration\n\nInvoice and Payment integrate with `@happyvertical/smrt-ledgers` via dynamic import (optional dependency). Invoice stores `arJournalId` and `revenueJournalId` as plain string references to ledger journals. `recognizeRevenue()` creates a balanced AR entry (DR: Accounts Receivable, CR: Revenue, CR: Tax Payable). `recordPayment()` creates a balanced cash receipt entry (DR: Cash, CR: Accounts Receivable). Both methods return null or throw if the ledgers package is not installed.\n\n`Payment.recordPayment()` claims the payment revision and commits the journal,\nentries, and completed payment in one database transaction. A failed completion\nrolls back the posting and restores the instance's settlement fields for retry.\nThe claimed persisted status is authoritative even if a caller locally resets\nstatus or marks the instance failed without saving. Concurrent or stale instances\nfail instead of posting twice; reload the payment\nand retry only if it is still pending. An already completed payment retains the\n`Payment already recorded` error. A caller's enclosing transaction remains the\nowner: if it rolls back after settlement returns, reload the payment before retry.\nThese guarantees cover new postings, not orphaned journals written by older\nversions. The returned journal uses the caller's database executor.\nBoth payment and refund journal lines retain the payment's explicit currency and\nexact amount; posting does not convert currencies or fall back to USD. When\nreporting accounts that contain different currencies, use the public\n`listPostedMovements` currency filter rather than combining their amounts.\n\n### Cross-Package References\n\nCustomer and Vendor link to `@happyvertical/smrt-profiles` via plain `profileId` string. Invoice and Payment reference `@happyvertical/smrt-ledgers` journals via plain string IDs (`arJournalId`, `revenueJournalId`, `journalId`). All models use `@TenantScoped({ mode: 'optional' })` with nullable `tenantId`.\n\n## Billing-period close\n\n`BillingRuntime` turns approved `@happyvertical/smrt-subscriptions` charges into\ninvoices for each billing owner, pushes them to a payment provider with\nprovider-calculated tax, posts revenue to the ledger, and applies the\nprovider's webhook events. Every provider call goes through\n`@happyvertical/accounting`; `createStripeBillingProvider()` adapts its Stripe\nprovider to the `BillingProvider` port. Money crossing the port is integer\nminor units.\n\n```ts\nimport { getAccountingProvider } from '@happyvertical/accounting';\nimport { SpendingPolicyEvaluator } from '@happyvertical/smrt-subscriptions';\nimport {\n  BillingRuntime,\n  createStripeBillingProvider,\n  enqueueBillingPeriodClose,\n  registerBillingRuntime,\n} from '@happyvertical/smrt-commerce';\n\nconst stripe = await getAccountingProvider({ type: 'stripe', secretKey });\nconst billing = await BillingRuntime.create({\n  db,\n  sellerTenantId: platformTenantId,\n  kind: 'provider', // or 'reseller' to bill a reseller's children\n  provider: createStripeBillingProvider({ stripe, webhookSecret }),\n  billingRelationships, // smrt-tenancy BillingRelationshipService\n  ledger: {\n    bookCurrency: 'USD', // ISO 4217; must equal the billing currency\n    arAccountId,\n    revenueAccountId,\n    taxAccountId,\n    cashAccountId,\n    prepaidCreditAccountId,\n  },\n  onPayerStanding: async ({ payerTenantId, standing, db }) => {\n    // suspend or reinstate the payer; runs in the event transaction\n  },\n});\n\n// One account per payer: its customer, tax location, and terms.\nawait billing.upsertAccount({\n  payerTenantId,\n  name: 'Network Co',\n  email: 'billing@example.test',\n  billingAddress: { country: 'CA', postalCode: 'T0L 0A0' },\n});\n\n// Optional: bill this payer from its activation date instead of calendar\n// months, prorating flat plans added mid-period (see \"Billing cycles\").\nawait billing.upsertAccount({\n  payerTenantId,\n  name: 'Network Co',\n  billingAnchorAt: activatedAt,\n  prorateFlatPlans: true,\n});\n\n// Close each payer's last ended period — safe to run on every schedule tick.\nregisterBillingRuntime('platform', billing);\nawait enqueueBillingPeriodClose({ runtime: 'platform' });\n\n// Webhook route: verify, enqueue, respond 2xx.\nconst intake = await billing.acceptWebhook(\n  rawBody,\n  request.headers.get('stripe-signature'),\n);\nif (intake.type?.endsWith(':unverified_credit_purchase')) {\n  // alert: a paid checkout claimed to buy credit but failed verification\n}\nawait billing.processEvents(); // or enqueueBillingEvents({ runtime: 'platform' })\n\n// Prepaid credit through provider checkout: tax is added on top when the\n// payer's account is taxed; `savePaymentMethod` keeps the card for top-ups.\nconst { url } = await billing.createCreditCheckout({\n  spendingPolicyId,\n  amount: 5000,\n  purchaseId: cartId,\n  savePaymentMethod: true,\n  successUrl,\n  cancelUrl,\n});\n\n// Card on file at signup: a setup checkout that charges nothing. Its\n// completion event makes the card the payer's default and adopts the billing\n// address collected at checkout as the tax location.\nconst setup = await billing.createCardSetupCheckout({\n  payerTenantId,\n  currency: 'CAD',\n  setupId: signupId,\n  successUrl,\n  cancelUrl,\n});\n\n// Automatic top-ups: charge the saved card when a balance would run out.\n// Accounts are taxed by default (`automaticTax`); a taxed account is charged\n// the credit plus provider-calculated tax (#3194).\nconst evaluator = await SpendingPolicyEvaluator.create({\n  db,\n  autoTopUp: billing.autoTopUpHook({ amount: () => 2500 }),\n});\n```\n\n- **What is billed.** A `provider` runtime bills `ClientCharge`s (and their\n  `BillingAdjustment`s) to the payer each charge names, plus monthly flat plans\n  it owns, to each subscriber's billing owner. A `reseller` runtime bills the\n  `RetailCharge`s its children owe it plus its own flat plans. Charges approved\n  before the period end are billed once, whatever period that is; flat plans\n  are billed in arrears for the payer's closed period (trials and\n  provider-managed subscriptions are skipped). One invoice per payer and\n  currency carries both kinds of lines.\n- **Replay safety.** Close, invoice, and line ids are derived from the payer,\n  currency, and period; each charge is claimed by exactly one close; the\n  provider invoice uses the close id as its idempotency key; and every step is\n  persisted before the next, so a retry resumes where it stopped. A lease stops\n  two workers advancing the same close. A close without a period also resumes\n  every unfinished close whose period has ended, even one the payer's current\n  schedule no longer produces (#3116). A payer whose charges net to a credit\n  gets no invoice; the credit is carried to its next invoice.\n- **Billing cycles (#3116).** A payer's periods follow its account's\n  `billingAnchorAt`. Unset (the default) they are UTC calendar months. Set,\n  they run monthly from the anchor at its UTC time of day; a day the month\n  lacks is clamped to its last day, always from the anchor itself (an anchor\n  on Jan 31 bills Jan 31 → Feb 28 → Mar 31). Before the anchor the schedule is\n  calendar months, and the anchor's own month ends at the anchor (a *stub*).\n  `closePeriod()` / `enqueueBillingPeriodClose()` with no period close each\n  payer's **last ended period on its own schedule**, so payers on different\n  anchors are closed by the same daily tick. An explicit\n  `{ periodStart, periodEnd }` closes that period for calendar payers (flat\n  plans only when it is a calendar month, as before) and for anchored payers\n  whose schedule has exactly that period. `billingPeriodFor(payer, at)` returns\n  a payer's current period; `billingPeriodContaining()`,\n  `lastEndedBillingPeriod()`, and `prorateMinorUnits()` are exported.\n- **Proration.** A flat plan is priced `price × billed time / cycle length`,\n  in integer minor units rounded half up (exact integer arithmetic; the\n  cycle is the period's own month, so February prorates over 28 or 29 days).\n  With `prorateFlatPlans` off (default) the billed time is the whole period\n  whenever the subscription was active in it and out of trial at its start —\n  the pre-#3116 behavior. With it on, the billed time is exactly the time the\n  subscription was active and out of trial: a subscription starting, leaving\n  trial, or canceled mid-period is billed pro rata. Proration happens before\n  the account's flat discount. Split into parts, prorated amounts can differ\n  from the full price by a minor unit.\n- **First period.** *Anchor at signup* (set `billingAnchorAt` to the\n  signup/activation instant): the first period is a full period from signup;\n  nothing before it is billed. *Bill from signup to the next anchor* (keep a\n  fixed anchor, or calendar months, and set `prorateFlatPlans`): the first\n  period is billed pro rata from signup. Items added later are prorated to the\n  payer's anchor when `prorateFlatPlans` is on and billed a full period\n  otherwise.\n- **Mid-period changes.** Billing is in arrears, so a cancellation needs no\n  credit: with proration the canceled period is billed up to `canceledAt`,\n  without it in full. A plan change is billed at the plan in effect at close\n  for the whole window (no plan-change proration yet, #3119), and a cancellation\n  back-dated into an already billed period is not credited — issue an\n  adjustment.\n- **No double billing across schedule changes.** Every flat-plan claim records\n  the exact time it bills, and a subscription's claims are numbered, so only\n  one worker can write the next claim and two can never claim the same time.\n  Moving an account from calendar months to an anchor, moving an anchor, or\n  moving a subscription to a payer on another schedule bills only time not yet\n  billed, prorated. For example, calendar months through February and then an\n  anchor on Mar 20 bills the Mar 1 → Mar 20 stub pro rata, then Mar 20 → Apr\n  20. Time around an already billed window is billed as separate lines, each\n  with its own service period. Stop workers running a pre-#3116 version\n  before relying on this: they claim flat plans outside the numbering.\n- **Service periods.** Each flat-plan invoice line carries its billed window\n  as `periodStart`/`periodEnd`, down to the provider port and on to Stripe's\n  invoice item `period`.\n- **Upgrading to #3116.** Additive schema only: `_smrt_billing_accounts` gains\n  `billing_anchor_at` (nullable) and `prorate_flat_plans` (default false), and\n  `_smrt_billing_line_sources` gains `chain_sequence` (default 0) and an index\n  on `(line_key, chain_sequence)`; run `smrt db:migrate`.\n  Existing accounts stay on calendar months, and claims written before the\n  upgrade (`<subscriptionId>:<periodStart>`, number 0) count as billed\n  coverage, so nothing is billed again after it.\n- **Tax** comes from the provider (Stripe Tax) using the account customer's\n  `defaultBillingAddress`; the invoice records it as `providerTaxAmount` in the\n  save that issues it. Billing invoices are ordinary money-model invoices in\n  the seller's tenant; period close seeds its standard codes if needed. Every\n  billing line is an explicit override to the seller's `out-of-scope` code, so\n  the seller's default code never taxes it a second time. Charges are written\n  before credits, so the running subtotal never goes negative. Revenue posting\n  uses `ledger.bookCurrency` and is idempotent.\n- **Events** are verified, stored in smrt-jobs' durable delivery inbox, and\n  applied against current provider state: paid invoices record a payment and\n  allocation; failures and overdue notices mark the payer `past_due` and its\n  flat-plan subscriptions `past_due`; an invoice written off at the provider\n  (`markInvoiceUncollectible(invoiceId)`, or in Stripe) is written off\n  locally and marks the payer `uncollectible` (no bad-debt journal is\n  posted; AR stays until it is paid or an operator journals it); payment\n  reinstates them, including a late payment of the written-off invoice. Dunning is the provider's.\n  Subscribe the webhook endpoint to `invoice.*`, `customer.subscription.*`,\n  `checkout.session.completed`, `checkout.session.async_payment_succeeded`,\n  and `payment_intent.*`.\n- **Prepaid credit** purchases credit a `period: 'balance'` spending policy\n  once per checkout session, paid by the policy's tenant or, for a delegated\n  balance, the parent that set it. Amounts are ISO 4217 minor units in any\n  currency the provider supports. When the payer's account is taxed\n  (`automaticTax`, not tax-exempt; override per call), provider tax is\n  charged on top and collected at checkout with the buyer's address: the\n  credit is the amount bought, the payment is the total collected, and the\n  tax is booked to the tax account. For a payer with a provider customer but\n  no local tax location, the address collected at checkout becomes its tax\n  location. `savePaymentMethod` requires a provider that can re-read the\n  checkout and set a default payment method, and is refused otherwise.\n- **Card on file (#3139).** `createCardSetupCheckout()` (or a credit purchase\n  with `savePaymentMethod`) saves the payer's card without charging it. On\n  completion the card becomes the provider customer's default and the\n  payer's default `PaymentInstrument`. When the checkout collected the billing\n  address (a taxed payer with no tax location), it becomes the payer's tax\n  location. `cardOnFile(payerTenantId)` returns `{ onFile, savedAt? }` from\n  the same check automatic charges use (a default card with the account's\n  provider customer), for \"card on file\" displays and signup activation;\n  the payer or a system context may call it (#3187).\n- **Automatically charged invoices.** With `autoChargeInvoices: true` on the\n  runtime, a payer with a default card is invoiced `charge_automatically`:\n  the provider charges the card after the invoice is sent, on its own\n  schedule, and retries failures. Each pushed invoice records the method in\n  `Invoice.collectionMethod` (`charge_automatically` or `send_invoice`; empty\n  for invoices pushed before #3190). Do not offer another payment rail on a\n  `charge_automatically` invoice the provider is still collecting.\n  Upgrading adds the `collection_method` column to `invoices` (run\n  `smrt db:migrate`). Activate service on the `current` standing\n  from the `paid` event, not on send; a failure marks the payer `past_due`.\n- **Automatic top-ups.** Taxed accounts (the default: `automaticTax` on, not\n  tax-exempt) are charged the credit plus provider-calculated tax (#3194):\n  the balance is credited the credit, the payment records the credit, and\n  the tax is booked to the tax account. `taxedAccounts: 'skip'` does not top\n  them up, and `'charge_untaxed'` charges them without tax. A taxed payer\n  without a tax location is not charged. A location Stripe rejects fails the\n  attempt with `failureCode: 'customer_tax_location_invalid'`\n  (`onAutoTopUpFailed`), and it is retried only after `retryAfterMs`. Pass\n  `onAutoTopUpSkipped` to learn when a needed top-up will not be charged\n  because of the payer's account. Its `reason` is `taxed_account`, `no_card`,\n  `no_account`, or `tax_location_invalid`, and more may be added. Use it, for\n  example, to ask the payer to top up by hand or to add a billing address; it is not called while a charge is processing, while a\n  declined card waits out `retryAfterMs`, or when the top-up is no longer\n  needed or `amount` declines it (#3189).\n  `billing.autoTopUpHook()` is the `autoTopUp` hook for\n  `SpendingPolicyEvaluator`: when a balance would run out it charges the\n  payer's saved card off-session (the delegating parent's, for a delegated\n  balance) and credits the balance only when the charge succeeds. A charge\n  still processing is credited from its `payment_intent.succeeded` event; a\n  decline or an authentication requirement credits nothing, closes the\n  attempt, and calls the runtime's `onAutoTopUpFailed` (ask the payer to\n  re-save their card with a setup checkout). One attempt runs per policy at a\n  time, retries of a declined card wait `retryAfterMs` (default one hour),\n  and the credit is granted exactly once however the outcome arrives.\n- **Product tax codes (#3194).** `taxCodes: { credit, invoice }` on the\n  runtime classifies prepaid credit (checkout purchases and taxed top-ups)\n  and billing-period invoice lines for Stripe Tax (`txcd_...`). Without it,\n  the Stripe account's default product tax code applies.\n- **Upgrading to #3194.** Requires `@happyvertical/accounting` 0.96 or later.\n  No schema change. Taxed accounts are now topped up with tax. To keep the\n  previous behaviour, pass `taxedAccounts: 'skip'`.\n- **Upgrading to #3139.** Requires `@happyvertical/accounting` 0.92 or later.\n  No schema change. Credit checkouts are now taxed for taxed accounts (pass\n  `automaticTax: false` to keep them untaxed), and Stripe customers are\n  created idempotently.\n\n### Payment rails: BTC and other crypto (#3138)\n\nA seller runtime can take payments on more than one **rail**. The issuing\n`provider` (Stripe) still issues, taxes, and emails every invoice; extra rails\nin `paymentProviders` let a payer choose, per payment, to pay an invoice or buy\nprepaid credit another way. The crypto rail runs short-lived, fiat-priced\ncheckouts through `@happyvertical/payments`' provider-neutral\n`CryptoCheckoutGateway` — BTCPay Server at launch — so another gateway can\nreplace BTCPay without changing this package or its consumers.\n\n```ts\nimport {\n  BillingRuntime,\n  createBtcPayBillingProvider,\n  createStripeBillingProvider,\n} from '@happyvertical/smrt-commerce';\n\nconst btcpay = createBtcPayBillingProvider({\n  baseUrl, apiKey, storeId,        // one BTCPay store per seller entity\n  webhookSecret, metadataSecret,   // from the host's secret store, by name\n  speedPolicy: 'LowMediumSpeed',   // settle after 2 confirmations (BTCPay offers 0/1/2/6)\n  rateSource: 'kraken',\n  minimumAmount: { CAD: 500, USD: 500 },\n});\nconst billing = await BillingRuntime.create({\n  db, sellerTenantId, kind: 'provider',\n  provider: createStripeBillingProvider({ stripe, webhookSecret }),\n  paymentProviders: [btcpay],\n  paymentPolicy: { latePaymentPolicy: 'review', refundBasis: 'original_native' },\n  billingRelationships,\n  ledger: { ...ledger, cryptoHoldingsAccountId, fxGainLossAccountId, feesAccountId },\n});\n\n// Prepaid credit or an issued invoice, paid with BTC:\nawait billing.createCreditCheckout({ ...purchase, provider: 'btcpay' });\nawait billing.createInvoicePayment({ invoiceId, provider: 'btcpay', purchaseId, successUrl, cancelUrl });\n\n// Webhook route for the rail (BTCPay signs with its own header):\nawait billing.acceptWebhook(rawBody, '', { provider: 'btcpay', headers: request.headers });\nawait billing.processEvents();\n```\n\n- **Refusals are typed (#3185).** `createInvoicePayment()` and\n  `createCreditCheckout()` throw `BillingPaymentRefusedError` for requests the\n  payer can correct, with a stable `code`: `not_found`, `not_payable`,\n  `payment_in_progress`, `nothing_due`, `invalid_amount`, `below_minimum`\n  (under the rail's `minimumAmount`), or `no_account`. Show its message as a\n  4xx; any other error is a server failure, and `TenantIsolationError` still\n  means the caller is not the payer. Treat an unknown code like\n  `not_payable`.\n- **Settlement is the gateway's.** Credit is granted and invoices are paid\n  only when the gateway reports `settled` under its own confirmation policy;\n  this package never counts confirmations. BTCPay offers 0, 1, 2 or 6\n  confirmations; the default is `LowMediumSpeed` (2 confirmations).\n- **Payment attempts.** Every rail checkout is a `BillingPaymentAttempt`\n  recording the locked fiat price, fiat and native amounts received, rate and\n  rate source, each payment's txid, rail and fee, a timeline of status changes,\n  and what settlement produced. `listPaymentAttempts()` feeds \"payment\n  confirming\" displays and operator queues; every filter applies before its\n  `limit` and `offset`, so paging through `{ unresolved: true }` lists every\n  open exception (flagged, not yet resolved) however old. `refreshPaymentAttempts()` is the polling\n  fallback for missed webhooks.\n- **Dunning pauses** for an invoice while a payment for it is confirming\n  (0-conf seen); if the payment then expires or is invalidated the payer's\n  standing is re-applied.\n- **Invoices paid on a rail** are closed at the issuer with\n  `markInvoicePaidOutOfBand` (Stripe `paid_out_of_band`), so Stripe stops\n  collecting; Stripe's own `paid` event then records nothing more.\n  `createInvoicePayment` refuses when the issuing provider cannot do that.\n  A written-off (uncollectible) invoice with an amount due can be paid on a\n  rail too, as it can by card at Stripe (#3188): the payment is recorded,\n  Stripe's invoice is closed out of band, and the payer returns to `current`;\n  the invoice keeps its `WRITTEN_OFF` status (its `amountPaid` shows the\n  recovery).\n- **Exceptions never auto-refund.** Underpaid, overpaid, late, manually marked\n  (at the gateway), invalidated-after-settlement, and paid-twice attempts are\n  flagged for an operator (`resolvePaymentAttempt`). Per-seller\n  `paymentPolicy` sets under/overpayment tolerances (basis points), late\n  payments (`review` | `accept`), manually marked checkouts, hold vs convert\n  (`conversionHandler`), and the refund basis.\n- **Ledger.** Receipts are booked at the locked fiat amount into\n  `cryptoHoldingsAccountId` (default `cashAccountId`); money received above\n  the price is booked as customer credit (prepaid-credit liability).\n  `recordManualRefund()` refunds from that excess first, then from purchased\n  credit (or an invoice payment kept as credit because the invoice was paid\n  elsewhere) — capped cumulatively, once per reference; an invoice payment\n  applied to its invoice is reversed at the issuer, not here.\n  `recordCryptoConversion()` posts a conversion with FX gain/loss.\n- **Upgrading.** Additive schema: `_smrt_billing_payment_attempts` (run\n  `smrt db:migrate`). A runtime without `paymentProviders` never reads it.\n- **One live payment per invoice.** The issuer's own `paid` event for an\n  invoice a rail closed out of band records nothing (the rail records it); an\n  out-of-band close made by someone else (wire, cheque) is recorded as an\n  `OTHER`-method payment; a real card payment made while a rail payment\n  confirms is recorded and the rail money is flagged `invoice_already_paid`.\n  An issuer close whose rail payment never settles is flagged\n  `out_of_band_without_settlement`: reopen the invoice at the issuer, then\n  `resolvePaymentAttempt()` it, after which a later out-of-band close is\n  recorded normally.\n- **Entities.** Each legal entity is its own seller runtime with its own\n  store, keys, and ledger. Inter-entity resale is ordinary reseller billing\n  between two sellers, payable on any rail the selling entity offers.\n\nSee [`AGENTS.md`](./AGENTS.md#billing-period-close-3060) for invariants and\nknown limits.\n\n## Dependencies\n\n- `@happyvertical/smrt-core` -- ORM and code generation\n- `@happyvertical/smrt-tenancy` -- multi-tenant scoping\n- `@happyvertical/smrt-subscriptions` -- charges, plans, and credit balances billed by period close\n- `@happyvertical/smrt-jobs` -- period-close jobs and the provider event inbox\n- `@happyvertical/accounting` -- payment-provider (Stripe) calls\n- `@happyvertical/smrt-types` -- shared type definitions\n- Peer: `@happyvertical/smrt-ledgers`, `@happyvertical/smrt-profiles`, `@happyvertical/smrt-svelte`\n\n## Contributor guide\n\nSee [`AGENTS.md`](./AGENTS.md) for package architecture, invariants, validation,\nand contributor guidance.\n\n## Pricing version UI\n\n`PricingVersionSummary` and `PricingVersionDecision` compose the quote revision\ncontract without adding a pricing ledger. Compare versions using\n`QuoteRevisionComparison`; the application owns every decision and native form\naction. See [pricing version presentation](agents/pricing-versions.md).\n\n## Commercial UI composition\n\nCustomer addresses and vendor/quote currencies use the shared localized code\nselectors while preserving native field names and rejected raw drafts. See\n[commercial UI contracts and backend boundaries](agents/commercial-ui.md) for\nnative forms, recovery, amount units and consumer adoption, plus the focused\n[customer/vendor](agents/customer-vendor-ui.md) and\n[quotation](agents/quote-ui.md) contracts for selector restrictions.\n\n## Customer and vendor contacts\n\n`Customer.contacts` and `Vendor.contacts` hold the people to reach at a party\n(`PartyContact`: `id`, `name`, `label`, `email`, `phone`, `address`) as a JSON\ncolumn; existing databases need `smrt db:migrate` for the new `contacts`\ncolumns. The form's contact rows are written with `savePartyContacts()`:\n\n```typescript\nimport {\n  applyPartyContactIntent,\n  PartyContactValidationError,\n  readPartyContactRows,\n  savePartyContacts,\n} from '@happyvertical/smrt-commerce';\n\nconst form = await request.formData();\n// Throws PartyContactPayloadError when the form's contactCount marker is absent\n// (block not rendered, or fieldNames differ), so a save never deletes by accident.\nconst rows = readPartyContactRows(form); // pass the form's fieldNames if overridden\nconst { contacts, handled } = applyPartyContactIntent(rows, String(form.get('intent')));\nif (handled) return { values: { ...values, contacts } }; // add/remove round trip, no save\ntry {\n  await savePartyContacts(vendors, vendorId, rows, { expectedTenantId });\n} catch (error) {\n  if (error instanceof PartyContactValidationError)\n    return fail(400, { values: { ...values, contacts: rows }, errors: { contacts: toMessages(error.errors) } });\n  throw error;\n}\n```\n\n`savePartyContacts` also accepts the `FormData` itself (with `fieldNames`) and\nreads it the same way. The rows replace the party's contacts: posted ids are kept, new rows get an\nid, unposted rows are removed, blank rows are dropped. See\n[customer/vendor UI](agents/customer-vendor-ui.md#contact-rows-3501).\n\n## Customer and vendor selectors\n\n`CustomerSelect` and `VendorSelect` from `@happyvertical/smrt-commerce/svelte`\nare searchable, field-sized pickers for a customer or vendor relation field.\nThey are registered in `COMMERCE_UI_SLOTS` with `selects:\n'@happyvertical/smrt-commerce:Customer'` / `':Vendor'`, so generic forms (via\n`findSelectorFor` over the manifest's `uiSelectors`) use them for any\n`@foreignKey` or `@crossPackageRef` field targeting those models.\n\nThey are presentation only. The caller owns the data: `search(query)` returns\nthe existing party DTOs (`CustomerDisplayData` / `VendorDisplayData`, whose\n`profile.name` is the label), and `resolve(id)` returns the record behind the\ncurrent value. Each row shows the profile name with status (and customer type).\nThe committed id, never the name, posts under `name`. Pass `onCreate` to offer a\n\"New customer\" / \"New vendor\" action; it receives the searched text, and a\nreturned record is selected.\n\n```svelte\n<CustomerSelect\n  name=\"customerId\"\n  bind:value={customerId}\n  search={(query) => customers.search(query)}\n  resolve={(id) => customers.byId(id)}\n  onCreate={(query) => openCustomerDialog(query)}\n/>\n```\n\nThe same models carry `@field({ ui: { widget } })` hints in the manifest:\n`textarea` on `Contract` (and subclass) `terms` and `notes`, `Customer`/`Vendor`\n`notes`, and `Invoice` notes and terms; `currency` (an ISO 4217 code picker) on\n`Contract`, `Vendor`, `Invoice` and `Payment` `currency`; `email`/`phone` on\n`Vendor.defaultContactEmail`/`defaultContactPhone`. See\n[customer and vendor selectors](agents/customer-vendor-ui.md#selectors-3602).\n\n## Invoice preparation UI\n\n`InvoiceEditor` from `@happyvertical/smrt-commerce/svelte` is the invoice form,\nbuilt on the commercial money model, v2, which is the only invoice money model.\nIt requires a `money` prop (`MoneyEditorProps`): a lossless draft with\ndescriptions, fractional quantities, unit prices, percentage or amount\ndiscounts and a tax code per line (inherited or overridden), plus the\nauthorized tax codes. Its previews run the same exact calculator the server\nuses, and the server re-resolves tax codes and recomputes every stored amount.\nAn issued document renders only its frozen stored snapshot.\n`InvoiceAllocationFields` and `InvoiceReview` add caller-owned sources and\napprovals. See [the editor contract](agents/invoice-preparation.md), the\n[line calculation helper](agents/invoice-calculations.md), and the\n[existing-database storage migration](agents/invoice-quantity.md).\n\n## Exact cost billing\n\nThe independent `@happyvertical/smrt-commerce/cost-billing` entry point provides\nexact signed reimbursement/fee calculations, ordered generic markup provenance,\nand explicit line or invoice tax rounding. Its opt-in ordered tax calculator\nsupports subset compounding with caller-selected signed invoice allocation.\nSee [the cost billing contract](agents/cost-billing.md).\nIt does not alter Invoice persistence, editor defaults or settlement behavior.\n\n### Purchase-order header editing\n\nImport `PurchaseOrderHeaderForm` from `@happyvertical/smrt-commerce/svelte` for a\nnative POST of vendor, reference, notes, expected date and ship-to fields. Pass\n`action`, `vendors` and raw `values`; return canonical field `errors` and the same\n`hiddenFields` after server validation. This header-only form leaves purchase\nallocations and totals unchanged. `PurchaseOrder` stores `expectedDate` and\n`shipTo` in existing STI metadata. See [the purchasing contract](agents/purchasing-ui.md#purchase-order-header)\nfor validation, retained values and transport details.\n\n### Invoice retention and release\n\n`configureInvoiceRetention` freezes an explicit retained minor-unit amount on an\nunpaid draft. Supply tenant, invoice, currency, expected invoice revision,\nrequest identity, actor, reason, evidence reference, and versioned host policy.\nThe supported `creditPolicy: 'retained-first'` is an explicit caller choice:\nissued credits reduce unreleased retention first, then current payable. Hosts\nmust choose and authorize their regional policy; Commerce supplies no legal\npercentage or release date default. Configuration cannot be overwritten; replace\nan unissued draft to change the original agreement.\n\n`releaseInvoiceRetention` appends evidence under the invoice's transaction lock.\nIt cannot release more than the currently retained remainder. Exact request\nreplays are safe; changed payloads or stale revisions fail. Both commands retain\ncaller transaction affinity. Original gross, tax, line snapshots and approved\nconfiguration stay unchanged. Credits and credit cancellation derive remaining\nretention without rewriting release history.\n\n`invoice.getPayableFacts()` separates `grossBalanceMinor`,\n`retainedRemainingMinor`, `currentlyDueMinor`, and `allocationCapMinor`. The\nallocation API enforces the current cap. `getAmountDue()` returns current due;\n`getBalance()` remains the signed gross balance. An invoice with paid current\ndue and unreleased retention is not fully paid or overdue. Display gross and\ncurrent payable separately; pass explicit current due and remaining holdback to\nthe exact retained invoice UI props rather than treating gross as payable.\nStored money facts include `payable` for retained invoices; MCP projection honors\nfield visibility for every source of the payable alias.\n\nProvider-controlled imports/automatic collection cannot acquire retention.\nAccounting export refuses unreleased retention until the provider has an\nexplicit payable representation; it never silently requests collection of\ngross. Fully released invoices use the existing gross accounting contract.\n\n## Retained invoice accounting\n\n`loadRetainedInvoiceAccountingSnapshot` supplies a read-only frozen document for\nreviewing item/tax mapping before posting; `toRetainedInvoiceAccountingInput`\nvalidates that reviewed mapping against those frozen lines. Both preserve tenant and caller executor\nscope and performs no provider operation. Generic accounting snapshot/export still\nrefuses unreleased retention. A supplied host-managed release due date may precede\nthe release date: preserving original past-due terms makes the released amount\nimmediately overdue rather than silently extending payment terms.\n\n`loadRetainedCreditAccountingSnapshot` and `toRetainedCreditAccountingInput`\nprovide the equivalent review path for an issued calculated credit. The caller\nsupplies both original invoice and credit IDs; the owning API verifies tenant,\ncustomer, currency and exact original lineage, then retains the existing frozen\nreader's issue and provider-realm checks. Generic retained-credit export remains\nblocked. Review never creates a credit adjustment or contacts a provider.\n\nThe public `syncRetainedInvoiceToAccounting`, `releaseRetainedInvoiceToAccounting`,\n`syncRetainedCreditToAccounting`, and `syncRetainedRefundToAccounting` commands\nimplement an explicit QuickBooks accrual reclassification contract. They require\nSDK `receivableTransfers` from the published SDK0.104.1 cohort\n(happyvertical/sdk#1414 / #1415; absent from SDK0.104.0).\nThey are available from the Commerce root and `/invoices` entry points.\n\nThe tenant must review/version the realm, environment, customer, AR account,\nretained-asset account and optional bank account mapping. Supported choices are\n`accrual`, `invoice-tax-point` and `host-managed` release due dates. Verified home\ncurrency only; no inferred FX, tax timing, recovery percentage or release date.\nHosts authorize actors before these server commands and provide an active tenant.\n\nFor gross10500/retained1000, the original approved invoice remains10500. A\nwithholding journal debits retained assets and credits customer AR1000; a\nzero-cash application links that credit to the original invoice. A partial release\ncreates the opposite journal and an explicitly dated host collection obligation.\nThe original invoice and its tax snapshot are unchanged. Provider collections and\nprovider tax overrides are unsupported for this contract.\n\nInitial export requires an issued, unpaid, uncredited, unreleased host-owned\ninvoice with no prior provider identity. Historical source-owned invoices require\na separate reconciled ownership contract and are rejected: importing history must\nnot duplicate its original journal. Existing local retention commands continue to\nreject provider-controlled releases; use the provider release command instead.\n\nRetained-first credits cancel the applicable retained asset through a release\njournal, apply the exported credit memo to that journal, and apply any due portion\nto the original invoice. Unapplied credit remains available for a refund. Refund\nsync requires an already completed local refund Payment, its cash journal and one\nexact source-credit allocation. It records the cash journal and applies the\nexisting credit; it performs no bank action and makes no settlement-certification\nclaim. That source payment/allocation becomes immutable. Provider-managed invoice\nvoids/write-offs, credit cancellation/reallocation and refund deletion are rejected\nrather than silently erasing remote postings. Corrective reversal contracts are\nnot implemented by these commands.\n\n### Recovery and concurrency\n\nEach external write has persisted request bytes/hash, attempt owner, status and\nvalidated readback. Confirmed earlier steps survive a later failure. Unknown or\ninterrupted steps block new operations; `reconcileRetainedAccountingStep` requires\nthe observed request/attempt, a known remote ID for exact provider readback, or\nexplicit authoritative absence evidence. An interrupted in-flight owner must be\nproven stopped. Reconciliation evidence and previous attempts remain recorded.\n`reconcileRetainedBaseInvoice` wraps the existing frozen invoice recovery contract.\n`reconcileRetainedCreditAccounting` resolves the reserved credit-memo creation step. Ordinary credit export is blocked for provider-retained sources.\n\nThe descriptor hash is not remote idempotency. The SDK uses documented QuickBooks\nrequest-ID duplicate handling; never create a new request identity merely because\na response was lost. Exact local replays reuse confirmed steps. Competing commands\nserialize under the tenant/source invoice locks, and releases check an observed\ninvoice revision. Source credits cannot change during an unfinished retention\noperation. Commands reject caller-owned Commerce money transactions because a\nprovider write cannot be rolled back with local SQL.\n\n`readRetainedInvoiceAccountingState` exposes the persisted operation/readback\nhistory. Canonical `Invoice.getPayableFacts()` remains the source of local gross,\nretained, released, credited and currently due amounts. Provider invoice\n`TotalAmt - Balance` includes noncash applications and must never be labeled cash\nreceived. SDK readback separates noncash applications, recorded cash journals and\nunverified bank settlement.\n\nValidation uses native SQLite/PostgreSQL persistence with mocked public provider\noperations, plus the SDK's exact request/readback fixtures. No live provider call\nor sandbox certification has been performed. Primary contract evidence and\nprovider-field limits are documented in the SDK Accounting README.\n\n### Incomplete supplier price evidence\n\nUse `recordPurchasePriceObservation`, `readPurchasePriceObservation`, and\n`completePurchasePriceObservation` for source quotes/orders that lack complete\nnet/tax/gross facts. Unknown totals remain null and no calculated or reportable\nContract exists until explicit reviewed completion. See\n[observed purchase prices](agents/observed-purchase-prices.md).\n"
     },
     {
       "path": "agents/invoice-quantity.md",
       "module": "invoice-quantity",
       "content": "# Invoice quantity persistence\n\nInvoiceLineItem accepts nonnegative decimal quantities with at most six decimal\nplaces. The `1.0` default declares a floating-point quantity column. Unit price,\ndiscount and amount stay safe integer minor units. Every save goes through the\ninvoice money aggregate, which recomputes the line and ignores\nany supplied amount. Tax comes from the line's resolved tax code, never from a\nstored rate. See the [commercial money model](money-model.md).\n\n## Existing integer columns\n\nRun a backup and pause invoice writers for this explicit migration. With a root\ndatabase handle and its known engine (`sqlite`, `postgres`, or `duckdb`), call\n`preflightInvoiceEditorStorage(db, engine)`, resolve every reported invalid row,\nthen `migrateInvoiceEditorStorage(db, engine)`. The preflight rejects negative,\nnonfinite, unsafe, excess-precision, and numerically non-roundtripping quantities.\nThe migration uses a transaction (and a PostgreSQL writer lock) and never rescales\nor rounds stored values. PostgreSQL widens INTEGER/BIGINT to DOUBLE PRECISION;\nDuckDB widens to DOUBLE. Repeating it leaves an already widened declaration alone.\nAn absent table is reported as absent and is never marked migrated.\n\nSQLite uses the public core table-rebuild planner to change the declaration to\nREAL while preserving existing columns, constraints, indexes, and triggers. If\nincoming foreign keys make that rebuild unsafe, the migration throws with the\nplanner reason and rolls back; it does not disable constraints or lose children.\nResolve that maintenance condition before deploying fractional writers. The\nmigration no longer adds an editor-state column. An `invoice_editor_state_json`\ncolumn that an earlier version added is left in place and unused. No schema\nmutation runs implicitly during runtime initialization or model save.\n\nThe actual DuckDB quantity/storage migration is tested. Complete Commerce model\npersistence on DuckDB is currently unsupported because its hard foreign keys use\nON UPDATE CASCADE, which DuckDB cannot preserve; the schema builder refuses that\ncontract. SQLite and PostgreSQL exercise complete save/reload model behavior.\n"
     },
+    {
+      "path": "agents/historical-sales.md",
+      "module": "historical-sales",
+      "content": "# Historical issued sales and original customer funds (#4081)\n\nHistorical intake is a separate source authority, not a new sale, send, or cash\nposting. Hosts must authorize the reviewer/importer, preserve original evidence,\nand call these public commands with the explicit active tenant. All writes use\none caller-affine transaction and the existing tenant money serialization lock.\n\n`recordHistoricalSalesMoney({ db, tenantId, invoiceId, requestId, evidenceRef,\nreview, source, facts, creditedSource? })` adopts an empty draft Invoice. Supply\noriginal integer minor-unit net/tax/gross, explicit signed-versus-magnitude\npolarity, original issue calendar date/time zone, and a nullable unknown due date.\nNormal calculated Invoice construction still defaults its due date as before.\nHistorical invoices expose `moneyAuthority: 'historical'` and a frozen source\nsnapshot. They create no InvoiceLineItems, fake quantities/rates, delivery event,\nAR/revenue journal, or provider invoice.\n\nA `detail: { kind: 'lines', lines }` source creates immutable\n`HistoricalSalesLine` children. The returned `{ snapshot, lines }` binds every\nsource key to a concrete `lineId`; use these IDs for consumer crosswalks.\nUnknown line tax, gross, quantity and rate remain null. Signed real adjustment\nlines retain their source values. The line net sum and every fully known other\nsum must exactly equal its corresponding original header.\n\nHistorical credits specify the exact original invoice/money snapshot and\noptional concrete original child IDs. Independent net, tax and gross capacity\nchecks never prorate a header. `getHistoricalSalesMoney` and\n`readHistoricalSalesLines` validate immutable retained authority.\n`getInvoiceMoneyFacts` includes the historical source projection. Exact header\nreports remain available through `listHistoricalSalesHeaderFacts` even when tax\nclassification is unknown. Breakdown-dependent tax reports require explicit\nreviewed component identities, taxable and net bases and classification; they\nnever infer a percentage from the source amount or borrow today's rate.\n\nOptional original `source.retention` records exact retained cents, an explicit\nretained-first credit policy, source actors/evidence and original calendar-dated\nreleases. This contract represents retention configured at original issue; its\noriginal effective date must equal the issue calendar date. A later retention\nconfiguration requires its own supported source event contract. Derived retention\nevents retain actual `recordedAt` and separate\n`effectiveOn`; as-of original cash eligibility uses the original dates. Ordinary\ncurrent retention configuration/release commands keep their existing behavior.\nOriginal credit/release sequencing rejects a release whose retained-first\ncapacity was already consumed; same-day ordering must be explicitly reviewed.\nRelease payment terms remain the original invoice due date, including an\nexplicitly unknown date. No jurisdiction terms are invented.\n\n`recordHistoricalCustomerFunds` retains original receipt/refund evidence and\nexplicit original deposit/release policy without creating a Payment or journal.\nOriginal accounting ownership and journal references are evidence, not authority\nto create duplicate original cash. Refunds identify either conserved unapplied\nfunds or one exact issued credit. Their headers immediately reserve refund\ncapacity, even before their original allocation row is imported.\n\n`recordHistoricalCustomerAllocation` records exact source allocation identities.\nReceipt applications affect the shared invoice paid balance once. Same-original\ncredit allocation rows and refund allocation rows audit their already-recorded\neconomic effects and do not reduce balances again. Cross-invoice transferable\ncredits are not represented by this contract. Same-day cash/credit chronology\nrequires explicit reviewed ordering; earlier original cash remains preserved\nwhen a later credit creates owed/refundable overpayment. Original cash dates\nremain separate from current balances and import timestamps.\n\n`getHistoricalCustomerFundsPosition` returns exact received/allocated/refunded/\navailable minor units. `applyHistoricalCustomerFunds` and\n`refundHistoricalCustomerFunds` perform NEW movements against remaining original\nfunds using explicit current active same-tenant accounts and the pinned original\npolicy terms. Applications use the existing liability-to-AR reclassification;\nrefunds use the existing journal-backed Payment command and retain the historical\nreceipt ID. Original receipts are never forged into completed Payments. Shared\nlive/historical paid/refund capacity prevents a second allocation or refund.\n\nStable source namespace/key identities replay exact facts across import runs\nwithout replacing the original importer or evidence. Changed facts/policy or\nsource-version reuse conflicts. Ordinary/generated model writes and deletion\ncannot mutate these immutable records. Provider synchronization and new revenue\nrecognition reject historical authority until an explicit supported historical\naccounting representation is supplied; exact original money is still readable.\n\nFocused evidence covers source/header immutability, concrete children, original\ncash/credit/refund chronology, conservation, CAD journals for new movements,\ncaller rollback and isolated PostgreSQL execution. Consumer historical adapters\nmust still map every source table and prove full-cohort reconciliation; adopting\nthese public facts alone is not full reference-import acceptance.\n\nCurrent explicitly dated retention releases append after the immutable original\nrelease prefix. Both remain readable without changing original dates or source\nauthority; replay binds the explicit date and caller rollback restores the\ncomplete release history. Provider releases retain their effective date in the\ncanonical retention history as well as provider evidence. Shared SQLite and\nPostgreSQL retention suites verify reload, exact retry, original-prefix tamper\nrefusal, and transactional rollback.\n\nHistorical cash allocations are validated as dated payment prefixes, independent\nof source import order. Backdated insertion rechecks later application dates;\nordinary public allocations retain their canonical allocatedAt chronology.\nSame-day credit ordering remains explicit. Later credits alone do not\nretroactively invalidate cash received before their issue date.\n\nCurrent `releaseInvoiceRetention` commands retain optional `sameDayCreditOrder`\nin their immutable evidence, alongside the effective calendar date. An exact\nretry must preserve that ordering; changing or removing it is a changed request.\nA later original credit import on the release date uses the retained ordering:\n`release-before-credit` releases first, while `credit-before-release` applies\nthe retained-first credit before checking remaining release capacity. Missing\nordering remains ambiguous and is refused rather than inferred from record time.\n### Bounded historical report scope\n\nHistorical header and tax reports apply the explicit tenant, historical money\nauthority, inclusive issue-date period, optional currency, and non-draft/non-cancelled\nstatus predicates in the collection query before enforcing the 100,000-document\nscope limit. Unrelated archived invoices do not consume a smaller report's limit;\nmore than 100,000 matching documents is refused rather than truncated.\n\nRegression design (#4063, PR #4101 comment 4300513731):\n\n| Invariant / trigger | Positive / refusal | Actor and executor | Runtime / evidence |\n| --- | --- | --- | --- |\n| Small matching period in a large tenant archive | Query-boundary fixture returns the single matching row only when all predicates precede the limit; matching scope above the cap still refuses | Explicit tenant and caller database; reads only | Focused Vitest; sparse overflow result avoids creating an archive |\n| Native collection scope | Exact inclusive boundaries, optional currency, historical authority and tenant isolation; draft/cancelled excluded | Active tenant, native test database | Focused SQLite and isolated PostgreSQL public historical-money + report proof |\n\nNo persistence behavior changes; rollback/retry and external-provider edges are\nnot applicable to this read-only query correction. The coordinator owns broader\ncohort validation and exact-head review under the resumed four-comment batch.\n\nEvidence on Node26/pnpm11.25.0: the focused archive-query regression failed against\n78f3ac856 (two failures, one pass), then passed after this query fix. The standard\n`node scripts/run-with-ci-postgres.mjs -- pnpm --filter @happyvertical/smrt-commerce exec vitest run src/__tests__/historical-sales-report-scope.test.ts src/__tests__/historical-sales-report-scope-native.test.ts`\nproof passed all five cases in9.80seconds, including actual SQLite and isolated\nPostgreSQL scope/tenant checks. No100,000-row fixture, production writes or schema\nchanges were needed. Full logs remain external at the2026-10-16 MVP session's\n`nonfinancial-import/scoped-sales-regression-base.log`, `scoped-sales-focused.log`\nand `scoped-sales-postgres.log`. Native token usage was unavailable.\n"
+    },
     {
       "path": "agents/payment-allocations.md",
       "module": "payment-allocations",
-      "content": "# Payment allocation integrity\n\n`PaymentAllocation.save()` owns the financial boundary for every direct or\ncollection write. Both payment and invoice must exist, belong to the same\nexact tenant (global is distinct), have the same customer and currency, and\nhave room for the positive safe-integer minor-unit amount. Zero-total invoices\nhave no room. Missing or zero-total invoice fixtures no longer bypass the cap.\nPending payments remain allocatable; this command does not establish settlement\nproof. Generated REST/MCP/CLI allocation writes remain closed. Applications\nmust authorize the actor before invoking these backend commands.\n\nUse `PaymentAllocationCollection.allocatePayment({ paymentId, allocations,\nallocatedBy })` for a split. Each allocation is `{ id, invoiceId, amount }`, with\na caller-generated stable UUID retained across retries. Exact replay\nreuses the existing rows without applying money again; an existing id with\ndifferent parents or amount fails. Replay preserves an already-paid invoice's\nrecorded payment date. Reversing\npayment clears that date; reaching full payment again records the new date.\nThe complete batch and invoice payment-status refresh share one transaction. Invoices must\nalready be in a status that permits payment (normally SENT); WRITTEN_OFF retains\nits terminal status. A failed leg rolls back every leg and parent revision.\nDirect allocation saves continue to leave status refresh to the caller. Allocation\nwrites advance both parent revisions: reload a previously held parent with\n`await parent.loadFromId()` before applying later edits or status refresh.\nStale parent saves continue to fail the core revision guard; no implicit\nrevision refresh bypasses another editor. In-package billing follows this rule.\n\nOnce inserted, allocation tenant/payment/invoice identity is immutable. Amount\ncorrections are capped against the other allocations. Parent saves reject\nchanges to tenant, customer, currency or amount that would invalidate committed\nallocations. A payment may be increased or reduced to its allocated total;\ninvoice totals continue to derive from persisted invoice lines where present.\nStandalone payments remain saveable when allocation storage has not been\nprovisioned. An existing allocation table always participates in validation;\nstorage probes and permission errors propagate instead of disabling the guard.\n\nAll participating writes bind collections to the owning transaction executor.\nThey claim parent revisions before reading balances. Concurrent writers can\nreceive a revision conflict or database serialization failure; reload and retry\nthe complete transaction with the same allocation ids. Never retry only the\nlast leg inside an already failed transaction. PostgreSQL Repeatable Read\nsnapshots fail closed through the same revision writes. SQLite serializes the\nowning write transaction. DuckDB is not a supported commerce allocation store:\nthe existing declared foreign keys require ON UPDATE CASCADE, which its DDL\nboundary explicitly refuses; no weaker schema is substituted.\n\n### Undelivered invoice payment progress\n\nAllocation may move an undelivered DRAFT invoice to PARTIAL or PAID without a\ncustomer delivery event. Neither operation invents `sentAt` or `viewedAt`.\nAfter allocations are removed, reload the parent and call\n`updatePaymentStatus(remainingTotal)` and `save()` within the caller transaction.\nZero remaining allocations restore DRAFT only for an undelivered invoice;\na delivered invoice returns to SENT/VIEWED according to its delivery history.\nDRAFT cannot conceal positive allocations. A DRAFT save checks both its supplied\ndelivery timestamps and the currently persisted timestamps, so clearing them\nlocally during reversal cannot bypass the undelivered requirement. This guard\ndoes not introduce an immutable lifetime delivery-history record.\n\nIf a prepaid invoice is actually delivered later, call `markSent()` and save.\nFor PARTIAL/PAID invoices it records the first `sentAt` while preserving payment\nstatus, paid amount, paid date and any existing view timestamp. Repeating this\ncall preserves the first send timestamp. It records the caller's delivery\nevent; it does not send a customer message or manufacture earlier delivery.\n"
+      "content": "# Payment allocation integrity\n\n`PaymentAllocation.save()` owns the financial boundary for every direct or\ncollection write. Both payment and invoice must exist, belong to the same\nexact tenant (global is distinct), have the same customer and currency, and\nhave room for the positive safe-integer minor-unit amount. Zero-total invoices\nhave no room. Missing or zero-total invoice fixtures no longer bypass the cap.\nPending payments remain allocatable; this command does not establish settlement\nproof. Generated REST/MCP/CLI allocation writes remain closed. Applications\nmust authorize the actor before invoking these backend commands.\n\nUse `PaymentAllocationCollection.allocatePayment({ paymentId, allocations,\nallocatedBy })` for a split. Each allocation is `{ id, invoiceId, amount }`, with\na caller-generated stable UUID retained across retries. Exact replay\nreuses the existing rows without applying money again; an existing id with\ndifferent parents or amount fails. Replay preserves an already-paid invoice's\nrecorded payment date. Reversing\npayment clears that date; reaching full payment again records the new date.\nThe complete batch and invoice payment-status refresh share one transaction. Invoices must\nalready be in a status that permits payment (normally SENT); WRITTEN_OFF retains\nits terminal status. A failed leg rolls back every leg and parent revision.\nDirect allocation saves continue to leave status refresh to the caller. Allocation\nwrites advance both parent revisions: reload a previously held parent with\n`await parent.loadFromId()` before applying later edits or status refresh.\nStale parent saves continue to fail the core revision guard; no implicit\nrevision refresh bypasses another editor. In-package billing follows this rule.\n\nOnce inserted, allocation tenant/payment/invoice identity is immutable. Amount\ncorrections are capped against the other allocations. Parent saves reject\nchanges to tenant, customer, currency or amount that would invalidate committed\nallocations. A payment may be increased or reduced to its allocated total;\ninvoice totals continue to derive from persisted invoice lines where present.\nStandalone payments remain saveable when allocation storage has not been\nprovisioned. An existing allocation table always participates in validation;\nstorage probes and permission errors propagate instead of disabling the guard.\n\nAll participating writes bind collections to the owning transaction executor.\nThey claim parent revisions before reading balances. Concurrent writers can\nreceive a revision conflict or database serialization failure; reload and retry\nthe complete transaction with the same allocation ids. Never retry only the\nlast leg inside an already failed transaction. PostgreSQL Repeatable Read\nsnapshots fail closed through the same revision writes. SQLite serializes the\nowning write transaction. DuckDB is not a supported commerce allocation store:\nthe existing declared foreign keys require ON UPDATE CASCADE, which its DDL\nboundary explicitly refuses; no weaker schema is substituted.\n\n### Undelivered invoice payment progress\n\nAllocation may move an undelivered DRAFT invoice to PARTIAL or PAID without a\ncustomer delivery event. Neither operation invents `sentAt` or `viewedAt`.\nAfter allocations are removed, reload the parent and call\n`updatePaymentStatus(remainingTotal)` and `save()` within the caller transaction.\nZero remaining allocations restore DRAFT only for an undelivered invoice;\na delivered invoice returns to SENT/VIEWED according to its delivery history.\nDRAFT cannot conceal positive allocations. A DRAFT save checks both its supplied\ndelivery timestamps and the currently persisted timestamps, so clearing them\nlocally during reversal cannot bypass the undelivered requirement. This guard\ndoes not introduce an immutable lifetime delivery-history record.\n\nIf a prepaid invoice is actually delivered later, call `markSent()` and save.\nFor PARTIAL/PAID invoices it records the first `sentAt` while preserving payment\nstatus, paid amount, paid date and any existing view timestamp. Repeating this\ncall preserves the first send timestamp. It records the caller's delivery\nevent; it does not send a customer message or manufacture earlier delivery.\n\n\n## Original settlement dates (#4099)\n\n`Payment.recordPayment` and `recordRefund` accept optional `effectiveOn`, a strict\nreal `YYYY-MM-DD` calendar date. Explicit dates set the posted journal and `paidAt`\nto noon UTC on that date; omission preserves current-clock ordinary posting.\nCustomer-funds commands retain their reviewed date and reject a conflicting\nexplicit override. Recording cash evidence does not initiate a provider transfer.\nCompleted or refunded payment settlement dates and journal identities are immutable,\nincluding direct save; correcting evidence requires an explicit reversal workflow.\nPosting retains the caller transaction and rejects duplicate completion.\n\nValidation: shared payment-posting contracts and customer-funds proofs pass on\nSQLite and PostgreSQL (55 passed, one PostgreSQL-only case skipped in the SQLite\nlane). They cover leap-day settlement, malformed/impossible dates, immutable\nreloads, duplicate posting, rollback, concurrency and conflicting managed dates.\nPackage typecheck/Svelte check (zero errors/warnings) and build pass. Initial\nfailures retained in the MVP evidence identified the missing direct-save date\nfreeze and an order-dependent journal assertion; both were corrected.\n\n## Allocation deletion versus retained-refund reservation (#4063 / PR #4101)\n\nDeletion claims the persisted Payment revision in its owning transaction before\nchecking provider or customer-funds authority. It holds that revision through the\nallocation DELETE. A retained-refund reservation uses the same Payment revision\nclaim when saving its binding, so a stale unbound parent read cannot authorize\nremoval after the provider reservation commits. If deletion commits first, the\nprovider reservation must fail its stale Payment claim before provider I/O.\nOrdinary deletion advances the Payment revision; reload held Payment instances\nbefore subsequent edits. Invoice status refresh remains caller-owned.\n\nThe accepted review fix is high risk because concurrent deletion could remove\nsettlement evidence already reserved by an external accounting operation. No API,\nschema, accounting mapping or bank execution contract changes.\n\n| Behavior / reachable trigger | Positive / negative case | Actor / executor / runtime | External edge / focused evidence |\n| --- | --- | --- | --- |\n| Direct allocation deletion | Ordinary unbound row deletes; failed outer transaction preserves row and parent revision | Active owning tenant; one caller transaction; SQLite and PostgreSQL | No bank I/O; dedicated allocation-delete suite |\n| Existing provider binding | Protected row remains and rejected delete rolls back parent revision; foreign tenant cannot delete | Owning versus foreign active tenant; transaction-bound parent claim; both dialects | Public retained-refund sync plus immutable binding readback |\n| Claimed deletion commits first | Provider reservation reaches its Payment revision claim, then fails without binding, refund reservation or provider I/O | Separate native PostgreSQL transactions; deterministic claim barriers | Public refund operation fails closed after its stale settlement evidence is removed |\n| Stale unbound parent read | Provider reservation commits while delete is paused, then stale delete fails and exact allocation remains | Separate native PostgreSQL transactions; deterministic read barrier | Real public provider saga with fake provider port; exact retry creates no extra provider operation |\n\nThe PostgreSQL concurrency interleaving is intentionally not run on SQLite:\nSQLite serializes the owning write transaction instead of allowing PostgreSQL's\nstale-read interleaving. Shared mutation/rollback/tenant/binding cases run on both.\nThe dedicated native test must fail against the pre-fix implementation before\nclaiming regression coverage. External outcome recovery and malformed provider\ninputs are unchanged and covered by the retained-accounting suite; no new provider\nrequest shape is introduced here.\n\nFocused validation: the dedicated SQLite/PostgreSQL test file passes all four\ncases; both PostgreSQL races use real independent transactions and explicit\nmethod barriers, without sleeps or mocked database results. The stale deletion\ncase fails against the unchanged base because deletion succeeds after provider\nreservation. Existing SQLite allocation-integrity and customer-funds suites also\npass (19 cases), including the managed reversal caller. Scoped model/test\nTypeScript passes. Run the dedicated PostgreSQL proof with the standard managed\n`run-with-ci-postgres.mjs` wrapper; it creates and cleans its own database.\n"
     },
     {
       "path": "agents/tax-codes.md",
@@ -19759,17 +21489,17 @@
     {
       "path": "agents/contract-money.md",
       "module": "contract-money",
-      "content": "# Contract money persistence\n\nContract money runs through `contract-money.ts`. A tenant operation enters\n`withTenantMoneyRuntime` before it locks and reloads its Contract and sibling\nlines on the scoped executor, resolves tax codes, and replaces the Contract\naggregate plus `DocumentTax` rows in the same transaction. Every Contract money\nwrite needs a tenant, and a tenant whose data needs the upgrade is refused (see\n[money data upgrade](money-upgrade.md)).\n\nDraft Contract line writes recompute every sibling. `subtotal` is tax-exclusive\nnet after discount, `taxAmount` is the component total, and `totalAmount` is\ntheir exact sum. Purchase component tax is recoverable only when the frozen\ncomponent says so. A Contract leaving draft snapshots registrations, party tax\nidentity, per-line component amounts, and `moneySnapshotId`; later money edits\nare refused with `FROZEN_DOCUMENT`.\n\n`SupplierQuote` uses purchase defaults and recoverability. Non-draft quotes\nfreeze just like other Contracts, but quote snapshots (including custom\ndescendants) are excluded by their hydrated STI subtype, not the mutable\n`contractType` scalar, from report candidates and purchase tax facts. Awarding\nrequires a separate PurchaseOrder.\n"
+      "content": "# Contract money persistence\n\nContract money runs through `contract-money.ts`. A tenant operation enters\n`withTenantMoneyRuntime` before it locks and reloads its Contract and sibling\nlines on the scoped executor, resolves tax codes, and replaces the Contract\naggregate plus `DocumentTax` rows in the same transaction. Every Contract money\nwrite needs a tenant, and a tenant whose data needs the upgrade is refused (see\n[money data upgrade](money-upgrade.md)).\n\nDraft Contract line writes recompute every sibling. `subtotal` is tax-exclusive\nnet after discount, `taxAmount` is the component total, and `totalAmount` is\ntheir exact sum. Purchase component tax is recoverable only when the frozen\ncomponent says so. A Contract leaving draft snapshots registrations, party tax\nidentity, per-line component amounts, and `moneySnapshotId`; later money edits\nare refused with `FROZEN_DOCUMENT`.\n\n`SupplierQuote` uses purchase defaults and recoverability. Non-draft quotes\nfreeze just like other Contracts, but quote snapshots (including custom\ndescendants) are excluded by their hydrated STI subtype, not the mutable\n`contractType` scalar, from report candidates and purchase tax facts. Awarding\nrequires a separate PurchaseOrder.\n\n## Received supplier monetary evidence\n\n`recordReceivedPurchaseMoney({ db, tenantId, contractId, requestId, evidenceRef,\nfacts, sourceQuote? })` records declared money on an existing empty draft\n`SupplierQuote` or `PurchaseOrder`. Authorize the human in the host first and\ncall inside its active tenant context. The command locks tenant settings and\nthe document on its transaction executor; an outer transaction can include\ncreation of the quote/order. It returns a `ReceivedPurchaseMoneySnapshot`;\n`getReceivedPurchaseMoney(contract)` returns that validated snapshot or `null`\nfor calculated documents. The public command is not an unguarded MCP action.\n\n```ts\nawait recordReceivedPurchaseMoney({\n  db, tenantId, contractId: quote.id, requestId: 'received-revision-1',\n  evidenceRef: 'supplier-document:revision-1',\n  facts: {\n    currency: 'CAD', netMinor: 10000, taxMinor: 537, grossMinor: 10537,\n    taxComponents: null,\n    detail: { kind: 'header-only' },\n  },\n});\n// Reload after the command; stale instances cannot overwrite its authority.\nconst received = await contracts.get({ id: quote.id }, { cache: false });\nreceived.status = ContractStatus.ACCEPTED;\nawait received.save();\n```\n\nThis sets `moneyAuthority='received'`; aggregate headers retain exactly\n10000/537/10537 without guessing a tax rate. The default `calculated` mode and\nits line/tax-code calculator are unchanged. Received facts become immutable\nwhen recorded. Exact retries return the original snapshot even after acceptance;\nchanged requests need a new document revision. Direct authority/evidence writes,\nheader edits, calculated lines, party/type changes and deleting received history\nare rejected. Acceptance sets the normal `moneySnapshotId` without recalculating\nsource amounts. A stable application quote identity may reference a distinct\ncanonical `SupplierQuote` for each immutable revision.\n\n`detail` must explicitly be `header-only` or `lines`. The latter supplies complete\nsource `netMinor`, `taxMinor`, `grossMinor` per uniquely keyed line with exact\naggregate reconciliation. Optional `quantityText`/`unitRateText` retain original\ndecimal text, never drive recomputation. When source lines are incomplete, retain\nthem in the referenced source evidence and use header-only monetary facts; do\nnot invent `ContractLineItem` quantities, tax lines, or allocations.\n\n`taxComponents:null` means unknown decomposition. `[]` means known zero tax,\nwhich requires `taxMinor:0`, but does not classify that zero as exempt/zero-rated.\nEach supplied component retains its source key, label, amount, explicit\n`classification` (`taxable`, `zero-rated`, `exempt`, `out-of-scope`, or `null`)\nand `recoverableMinor` (including explicit zero or unknown `null`). Optional\n`taxCodeId`, `taxComponentId` and `taxableMinor` remain unknown when omitted. Values are exact\nsafe nonnegative minor units; sums use integer arithmetic. No recoverability,\nrate, taxable basis or classification is inferred from a label or amount.\n\nAn order can include\n`sourceQuote:{contractId,relationship:'copy'|'negotiated'}`. The quote must be\naccepted, frozen, received, and match tenant/vendor/currency. `copy` requires\nidentical facts. `negotiated` requires separately supplied approved monetary\nfacts and a separate evidence reference; it never prorates a quote. The command\nrecords lineage but does not manufacture acceptance or financial approvals.\n\nReceived SupplierQuotes remain excluded from incurred purchase-tax reporting.\nPurchaseOrders retain their existing report eligibility. For a received order,\npublic document report facts project explicit source amounts without creating\ncalculated `DocumentTax` rows or fictitious rates. Each report component must\nhave an explicit classification, tenant-owned tax code, taxable basis, recoverable amount and, for\n`taxable`, a tenant-owned `taxComponentId`. Missing facts raise\n`ReceivedPurchaseTaxClassificationRequired` with code\n`RECEIVED_PURCHASE_TAX_CLASSIFICATION_REQUIRED` and the affected order ID. This\nblocks only a report whose tenant/date/currency window includes that order;\nrecording, accepting and awarding unknown-classification evidence remains valid.\nExisting calculated PO reporting is unchanged. Correct classification through an\nexplicit reviewed replacement revision and cancellation of the superseded\nreport-eligible order, preserving its history; never rewrite frozen evidence or\nsilently omit the unknown order from a report.\n\nThe two added Contract fields use the normal generated schema/migration flow;\napply the generated migration before using the new public command on an existing\ndatabase. Native SQLite/PostgreSQL acceptance is in\n`received-purchase-money.test.ts` / `received-purchase-money.optional.test.ts`.\nDuckDB retains the existing unsupported native Contract foreign-key boundary.\n"
     },
     {
       "path": "agents/money-model.md",
       "module": "money-model",
-      "content": "# Commercial money model\n\nThis guide names the public commerce money contract. The exact input and result\nshapes, validation codes, and worked calculator examples live in the\n[calculator guide](money-calculator.md) and\n[package documentation](../../../docs/content/commerce-money.md). Money values\nare signed safe-integer minor units; calculator tax percentages are exact text,\nso `'5'` means 5%. The `InvoiceLineItem.taxRate` and\n`ContractLineItem.taxRate` fields are server-derived fractions of the resolved\ncomponents (`0.05` means 5%); they are never tax inputs.\n\n## Calculation contract\n\n`calculateMoneyDocument()` accepts `exclusive`, `inclusive`, and `none` line\namount modes. It first computes quantity times unit price, applies the one\nchosen discount, and returns the post-discount amount, tax components, net, and\nline total. `exclusive` line amounts are tax-exclusive net; `inclusive` line\namounts are the visible gross and derive net by removing tax; `none` has zero\ntax and requires an out-of-scope code. `subtotalMinor`, `taxMinor`, and\n`totalMinor` are document totals. `discountTotalMinor` is informational because\nthe line discounts were already applied; consumers must not subtract it again.\n\nThe `line` rounding scope rounds each line/component. The `document` scope\nrounds each shared component's exact total, truncates each allocation toward\nzero, and gives signed residual minor units to the largest remainders, with\nline-ID code-unit order breaking ties. It leaves no document residual. Across\n`n` small lines, the two scopes can differ by up to `ceil(n / 2)` minor units\nper component. Store the chosen scope; do not silently substitute a later\nsetting. `MoneyValidationError.code` is the public branch point for invalid\nmoney, discounts, tax-code state and scope, unsupported compound tax, frozen\nrecords, and unsafe values.\n\nTax-code resolution is pure once the caller has loaded authorized codes. It\nuses a line override, customer exemption, product code, customer code, and app\ndefault in that order. An unresolved exclusive or inclusive line is a genuine\nzero-tax, null-code case; it is not an out-of-scope inference. The tax-code\ncatalogue, seeds, registrations, and cookbook boundary are documented in\n[tax codes](tax-codes.md).\n\n## Stored Invoice facts\n\nThere is one money model. Saving a draft resolves its current tax settings\nonce and atomically writes the header, line snapshots, and `DocumentTax` rows.\nEvery money document needs a tenant, and data written by an earlier version is\nrefused until it is upgraded ([money data upgrade](money-upgrade.md)). The detailed persistence, freeze, preview, credit-note, and\nrefund contracts are in [document money](document-money.md).\n\nOnce an Invoice leaves `DRAFT`, or receives an AR journal, its money snapshot\nis frozen. Reads use those stored values and must not recompute issued tax from\nnew defaults. `DocumentTax` is a derived, read-only per-document/code/component\nsnapshot with currency, code and component identities and labels, kind, exact\npercent, liability account, taxable, tax, and recoverable minor-unit values.\nIt also represents non-taxable and unassigned zero-tax rows so reporting does\nnot invent a taxable component.\n\nA credit note is an `Invoice` with `kind: 'credit_note'`. It stores positive\namounts; posting, reporting, and accounting adapters apply that direction once.\nIssued-credit capacity and refunds are stable Invoice behavior. A refund is\na positive `Payment` of kind `refund`, allocated only to a credit note. See\n[document money](document-money.md) before presenting either balance as an\nordinary incoming payment.\n\n## Invoice MCP `get` projection\n\nThe standard Invoice MCP `get` tool uses `serializeInvoiceMcpGet`. For a\ntenant invoice, the optional `money` value is the stored `InvoiceMoneyFacts`\nprojection: its header, line snapshots, and `DocumentTax` facts are read from\nthe stored snapshot and are never recalculated. An invoice without an id or\ntenant returns the ordinary public Invoice projection.\n\nA tenant whose data needs the upgrade refuses this read with\n`COMMERCE_DATA_NEEDS_UPGRADE`. If the caller's `PublicJsonOptions` hide any Invoice,\n`InvoiceLineItem`, or `DocumentTax` field needed by the money projection, the\nserializer returns the base Invoice and omits the entire `money` alias. It does\nnot expose restricted values through a partial plain-object alias.\n\nThis applies only to standard MCP `get`. Invoice list and MCP write behavior\nremain their existing public contracts. The general serializer configuration,\nauthorization order, and projection rule are in [core MCP get\nserializers](../../core/agents/generators.md#mcp-get-serializers).\n\n## Reporting and integrations\n\nThe materialized `TaxSummaryReport` and its public descriptor/drilldown bridge\nread stored Invoice `DocumentTax` facts under the tenant money lock. See\n[tax summary aggregation](tax-summary.md). Commerce exports\n`createTaxSummaryMaterializedReportHost()` for an application-owned,\nserver-only host; register that host in the app's fixed report-host registry to\nopt into the generic `MaterializedReportTable` and its tenant-scoped drilldown\nroute. The host binds the authenticated tenant, principal, and\n`taxsummaryreports.read` permission; browser input supplies only a row id\nand visible column id.\n\nThe accounting snapshot mapper consumes frozen facts and never re-calculates a\nrate or allocation. It maps an inclusive line to the accounting SDK's\n`TaxInclusiveAmt`; tenant mappings provide provider tax-code and component-rate\nidentities. The QuickBooks sync boundary persists SDK 0.103.7 invoice or credit\nmemo request descriptors before provider I/O, refuses competing writes, and\nrequires explicit reconciliation after an unknown outcome. Its supported\ninputs and recovery contract are documented in [accounting snapshot\nmapper](accounting-snapshot-mapper.md).\n\n## Deliberate boundaries\n\nUpgrading data written by an earlier version is documented in\n[money data upgrade](money-upgrade.md). Contract money persistence remains a separate aggregate contract; production report\nhosting is an application opt-in over the public host described above. The\nmodel also does not provide currency conversion, cash-basis/deposit accounting,\npartial recoverability, period locking, or compound tax.\n"
+      "content": "# Commercial money model\n\nThis guide names the public commerce money contract. The exact input and result\nshapes, validation codes, and worked calculator examples live in the\n[calculator guide](money-calculator.md) and\n[package documentation](../../../docs/content/commerce-money.md). Money values\nare signed safe-integer minor units; calculator tax percentages are exact text,\nso `'5'` means 5%. The `InvoiceLineItem.taxRate` and\n`ContractLineItem.taxRate` fields are server-derived fractions of the resolved\ncomponents (`0.05` means 5%); they are never tax inputs.\n\n## Calculation contract\n\n`calculateMoneyDocument()` accepts `exclusive`, `inclusive`, and `none` line\namount modes. It first computes quantity times unit price, applies the one\nchosen discount, and returns the post-discount amount, tax components, net, and\nline total. `exclusive` line amounts are tax-exclusive net; `inclusive` line\namounts are the visible gross and derive net by removing tax; `none` has zero\ntax and requires an out-of-scope code. `subtotalMinor`, `taxMinor`, and\n`totalMinor` are document totals. `discountTotalMinor` is informational because\nthe line discounts were already applied; consumers must not subtract it again.\n\nThe `line` rounding scope rounds each line/component. The `document` scope\nrounds each shared component's exact total, truncates each allocation toward\nzero, and gives signed residual minor units to the largest remainders, with\nline-ID code-unit order breaking ties. It leaves no document residual. Across\n`n` small lines, the two scopes can differ by up to `ceil(n / 2)` minor units\nper component. Store the chosen scope; do not silently substitute a later\nsetting. `MoneyValidationError.code` is the public branch point for invalid\nmoney, discounts, tax-code state and scope, contradictory compound dependencies, frozen\nrecords, and unsafe values.\n\nTax-code resolution is pure once the caller has loaded authorized codes. It\nuses a line override, customer exemption, product code, customer code, and app\ndefault in that order. An unresolved exclusive or inclusive line is a genuine\nzero-tax, null-code case; it is not an out-of-scope inference. The tax-code\ncatalogue, seeds, registrations, and cookbook boundary are documented in\n[tax codes](tax-codes.md).\n\n## Stored Invoice facts\n\nThere is one money model. Saving a draft resolves its current tax settings\nonce and atomically writes the header, line snapshots, and `DocumentTax` rows.\nEvery money document needs a tenant, and data written by an earlier version is\nrefused until it is upgraded ([money data upgrade](money-upgrade.md)). The detailed persistence, freeze, preview, credit-note, and\nrefund contracts are in [document money](document-money.md).\n\nOnce an Invoice leaves `DRAFT`, or receives an AR journal, its money snapshot\nis frozen. Reads use those stored values and must not recompute issued tax from\nnew defaults. `DocumentTax` is a derived, read-only per-document/code/component\nsnapshot with currency, code and component identities and labels, kind, exact\npercent, liability account, taxable, tax, and recoverable minor-unit values.\nIt also represents non-taxable and unassigned zero-tax rows so reporting does\nnot invent a taxable component.\n\nA credit note is an `Invoice` with `kind: 'credit_note'`. It stores positive\namounts; posting, reporting, and accounting adapters apply that direction once.\nIssued-credit capacity and refunds are stable Invoice behavior. A refund is\na positive `Payment` of kind `refund`, allocated only to a credit note. See\n[document money](document-money.md) before presenting either balance as an\nordinary incoming payment.\n\n## Invoice MCP `get` projection\n\nThe standard Invoice MCP `get` tool uses `serializeInvoiceMcpGet`. For a\ntenant invoice, the optional `money` value is the stored `InvoiceMoneyFacts`\nprojection: its header, line snapshots, and `DocumentTax` facts are read from\nthe stored snapshot and are never recalculated. An invoice without an id or\ntenant returns the ordinary public Invoice projection.\n\nA tenant whose data needs the upgrade refuses this read with\n`COMMERCE_DATA_NEEDS_UPGRADE`. If the caller's `PublicJsonOptions` hide any Invoice,\n`InvoiceLineItem`, or `DocumentTax` field needed by the money projection, the\nserializer returns the base Invoice and omits the entire `money` alias. It does\nnot expose restricted values through a partial plain-object alias.\n\nThis applies only to standard MCP `get`. Invoice list and MCP write behavior\nremain their existing public contracts. The general serializer configuration,\nauthorization order, and projection rule are in [core MCP get\nserializers](../../core/agents/generators.md#mcp-get-serializers).\n\n## Reporting and integrations\n\nThe materialized `TaxSummaryReport` and its public descriptor/drilldown bridge\nread stored Invoice `DocumentTax` facts under the tenant money lock. See\n[tax summary aggregation](tax-summary.md). Commerce exports\n`createTaxSummaryMaterializedReportHost()` for an application-owned,\nserver-only host; register that host in the app's fixed report-host registry to\nopt into the generic `MaterializedReportTable` and its tenant-scoped drilldown\nroute. The host binds the authenticated tenant, principal, and\n`taxsummaryreports.read` permission; browser input supplies only a row id\nand visible column id.\n\nThe accounting snapshot mapper consumes frozen facts and never re-calculates a\nrate or allocation. It maps an inclusive line to the accounting SDK's\n`TaxInclusiveAmt`; tenant mappings provide provider tax-code and component-rate\nidentities. The QuickBooks sync boundary persists SDK 0.103.7 invoice or credit\nmemo request descriptors before provider I/O, refuses competing writes, and\nrequires explicit reconciliation after an unknown outcome. Its supported\ninputs and recovery contract are documented in [accounting snapshot\nmapper](accounting-snapshot-mapper.md).\n\n## Deliberate boundaries\n\nUpgrading data written by an earlier version is documented in\n[money data upgrade](money-upgrade.md). Contract money persistence remains a separate aggregate contract; production report\nhosting is an application opt-in over the public host described above. The\nmodel also does not provide currency conversion or general cash-basis accounting,\npartial recoverability or period locking. Ordered compound taxes are supported as\ndocumented in [money calculator](money-calculator.md). Explicit invoice-tax-point\ncustomer deposits and unallocated cash are provided by the separate\n[customer-funds authority](customer-funds.md), not by invoice pricing.\n"
     },
     {
       "path": "agents/money-calculator.md",
       "module": "money-calculator",
-      "content": "# Money calculator\n\n`src/money.ts` is the Svelte-free authority for commercial document arithmetic.\nImport it from `@happyvertical/smrt-commerce/money` (or the package root).\n\n- Inputs are signed safe-integer minor units. Quantity and percent values have at\n  most six decimal places; calculations use exact `BigInt` rationals and round\n  half away from zero. Currency must be a supported ISO 4217 code with a defined\n  minor unit; the exponent validates the document currency but does not rescale\n  already-minor-unit inputs.\n- `lineAmountType` is `exclusive`, `inclusive`, or `none`. Inclusive `amountMinor`\n  is the customer-visible gross; `netMinor = amountMinor - taxMinor`.\n- `roundingScope: 'line'` rounds each line/component. `document` rounds the exact\n  sum for each shared component, then allocates from truncation toward zero by\n  signed largest remainder. Ties use code-unit line ID order, so input order does\n  not affect allocation. The residual's sign, including mixed signed lines, is\n  authoritative.\n- `taxes` is split by tax code and component for persistence. Shared components\n  are rounded across codes at document scope. Non-taxable codes use a null\n  component row with zero tax and taxable minor units equal to summed line net.\n  A genuinely unassigned exclusive/inclusive line uses `taxCode: null` and emits\n  `{ taxCodeId: null, taxComponentId: null }`; no synthetic ID is persisted.\n- Resolve already-loaded codes with `resolveLineTaxCode()`. `none` mode always\n  chooses the supplied out-of-scope code before an override. Active/scope checks\n  happen during resolution; issued snapshots are not passed back through it.\n  Missing exempt/out-of-scope seeds fail closed and never fall through to a\n  taxable default.\n- Discounts are either percent or signed minor units. An amount discount carries\n  the gross sign. Editors may accept a positive magnitude, then apply the sign.\n\nAll business rejections use `MoneyValidationError`. The stable tax-code shape\ncodes include `TAX_CODE_DUPLICATE_COMPONENT`,\n`TAX_CODE_NON_TAXABLE_COMPONENTS`, and `TAX_CODE_TAXABLE_EMPTY`, in addition to\n`TAX_CODE_NOT_FOUND`, `TAX_CODE_KIND`, `TAX_COMPONENT_RATE_CONFLICT`, and the\nshared input, discount, percent, compound, state, scope, safety, freeze, and\ncurrency codes exported as `MoneyValidationCode`.\n\n`calculateInvoiceMinorLine(input)` in `src/svelte/invoices/calculations.ts`\n(also exported from `@happyvertical/smrt-commerce/invoices`) runs one line\nthrough this calculator with a single-component code built from its resolved\nfraction. It takes no options. Its discount is signed minor units and passes\nthrough unchanged, and its ties round half away from zero for negative\nlines too. Editor magnitude normalization happens before constructing that\ninput. See [invoice line calculation](invoice-calculations.md).\n"
+      "content": "# Money calculator\n\n`src/money.ts` is the Svelte-free authority for commercial document arithmetic.\nImport it from `@happyvertical/smrt-commerce/money` (or the package root).\n\n- Inputs are signed safe-integer minor units. Quantity and percent values have at\n  most six decimal places; calculations use exact `BigInt` rationals and round\n  half away from zero. Currency must be a supported ISO 4217 code with a defined\n  minor unit; the exponent validates the document currency but does not rescale\n  already-minor-unit inputs.\n- `lineAmountType` is `exclusive`, `inclusive`, or `none`. Inclusive `amountMinor`\n  is the customer-visible gross; `netMinor = amountMinor - taxMinor`.\n- `roundingScope: 'line'` rounds each line/component. `document` rounds the exact\n  sum for each shared component, then allocates from truncation toward zero by\n  signed largest remainder. Ties use code-unit line ID order, so input order does\n  not affect allocation. The residual's sign, including mixed signed lines, is\n  authoritative.\n- `taxes` is split by tax code and component for persistence. Shared components\n  are rounded across codes at document scope. Non-taxable codes use a null\n  component row with zero tax and taxable minor units equal to summed line net.\n  A genuinely unassigned exclusive/inclusive line uses `taxCode: null` and emits\n  `{ taxCodeId: null, taxComponentId: null }`; no synthetic ID is persisted.\n- Resolve already-loaded codes with `resolveLineTaxCode()`. `none` mode always\n  chooses the supplied out-of-scope code before an override. Active/scope checks\n  happen during resolution; issued snapshots are not passed back through it.\n  Missing exempt/out-of-scope seeds fail closed and never fall through to a\n  taxable default.\n- Discounts are either percent or signed minor units. An amount discount carries\n  the gross sign. Editors may accept a positive magnitude, then apply the sign.\n\nAll business rejections use `MoneyValidationError`. The stable tax-code shape\ncodes include `TAX_CODE_DUPLICATE_COMPONENT`,\n`TAX_CODE_NON_TAXABLE_COMPONENTS`, and `TAX_CODE_TAXABLE_EMPTY`, in addition to\n`TAX_CODE_NOT_FOUND`, `TAX_CODE_KIND`, `TAX_COMPONENT_RATE_CONFLICT`, and the\nshared input, discount, percent, compound, state, scope, safety, freeze, and\ncurrency codes exported as `MoneyValidationCode`.\n\n`calculateInvoiceMinorLine(input)` in `src/svelte/invoices/calculations.ts`\n(also exported from `@happyvertical/smrt-commerce/invoices`) runs one line\nthrough this calculator with a single-component code built from its resolved\nfraction. It takes no options. Its discount is signed minor units and passes\nthrough unchanged, and its ties round half away from zero for negative\nlines too. Editor magnitude normalization happens before constructing that\ninput. See [invoice line calculation](invoice-calculations.md).\n\n## Ordered compound taxes\n\n`TaxComponentInput.compound: true` uses every preceding component in the same\nordered tax code. Different applicable line/category subsets use different codes;\nno missing predecessor is invented. Exclusive and explicit-net credit inputs use\nprior rounded taxes at line scope or prior allocated taxes at document scope.\nShared components retain one rate. Contradictory dependency orders across codes\nfail with `TAX_COMPONENT_DEPENDENCY_CYCLE`.\n\nInclusive extraction computes exact ordered rational factors, then rounds or\nallocates the extracted component taxes. Net is the gross-minus-tax residual.\nThis is not a promise that an inclusive extraction reverses an exclusive rounded\ncalculation penny-for-penny. Signed reversals use the same symmetric rules.\n\nCompound result components and frozen line snapshots carry `compound: true` and\n`taxableMinor`. Component tax rows preserve this actual basis, with `netMinor`\nseparate so kind/revenue summaries do not include tax-on-tax as net revenue.\nHistorical additive snapshots omit these optional fields. Credits reconstruct the\nfrozen ordered components; a final credit consumes the remaining frozen bases and\ntaxes. The compatibility line `taxRate` is the observed effective tax/net ratio\nfor compound lines, not a flattened statutory rate; never use it to reconstruct\na document. Use component snapshots and canonical minor-unit totals.\n\n`DocumentTax.netMinor` is a nullable generated-schema field. Additive records use\nnull and retain their previous reporting shape. Upgrade schemas before projecting\nreports. Received purchase components may declare a taxable basis above net;\nwhen that occurs their explicit `netMinor` is required for report classification.\nRecording evidence remains allowed without that classification.\n\nCompound accounting synchronization uses the public SDK ordered snapshot contract\n([SDK #1412](https://github.com/happyvertical/sdk/issues/1412)). The mapper preserves\noriginal rates, exact taxable bases and caller-verified realm TaxCode ordering.\nMissing or mismatched reviewed mapping still raises `ACCOUNTING_SYNC_UNSUPPORTED`.\nIt never substitutes a flattened rate. Deployment requires the SDK release that\ncontains this public contract; the prior additive-only SDK cannot accept it.\n"
     },
     {
       "path": "agents/commercial-ui.md",
@@ -19790,6 +21520,26 @@
       "path": "agents/cost-billing.md",
       "module": "cost-billing",
       "content": "# Exact cost billing\n\n`@happyvertical/smrt-commerce/cost-billing` is an independent, transport-neutral\nentry point without model, server or Svelte dependencies. It does not persist,\npost, authorize, select a currency/jurisdiction, or implement credit-note lifecycle.\nIt does not change Invoice calculations or the invoice editor; both use the\ncommerce money calculator, whose ties also round half away from zero. The\n`roundingScope: 'invoice'` behavior in this guide is a standalone cost-billing\nconvention; document arithmetic uses `roundingScope: 'document'` and stores\nallocated tax facts. See the [commercial money model](money-model.md) and\n[money calculator](money-calculator.md).\n\nCall `resolveCostMarkup(overrides)` with caller-approved precedence, most specific\nfirst. Each item has `source`, optional `policy` and `version`, and optional\n`percent`. The first defined percent wins, including `\"0\"`. At least one is\nrequired; even shadowed inputs are validated. The result contains the percent,\nselected index, and detached ordered provenance. Persist accepted snapshots in\nthe owning application; these helpers never reprice them automatically.\n\nCall `calculateCostBilling({ basisMinor, mode, markup })` with that result. Money\nis signed safe-integer minor units in a single caller-selected currency. The\nbasis is explicitly chosen by the caller (for example excluding recoverable tax).\n`reimbursement-plus-fee` returns principal once plus rounded fee; `fee-only`\nreturns only the fee; `nonbillable` and `fixed-contract` return zero charge.\nThe result includes `principalMinor`, `feeMinor`, `totalMinor`, and provenance.\nPercent strings use plain nonnegative decimal notation, range 0–100000 percent,\nat most six fractional places, without whitespace, exponent or leading zeroes.\nThe finite range and scale bound input parsing and arithmetic resource use; they\nare API limits, not tax or industry policy. Arithmetic uses BigInt intermediates and half-away-from-zero rounding. Invalid\ninputs, unknown modes, inconsistent provenance and unsafe outputs throw.\n\n`calculateCostBillingTax({ lines, rules, roundingScope })` accepts line\n`id`, signed `amountMinor`, and `category`; rules explicitly map every used\ncategory to `{ id, percent }` components. An empty component array explicitly\nmeans exempt. Components are additive, never compounded. Shared component IDs\nmust use equal rates across categories; distinct rate regimes need distinct IDs.\nThe caller owns taxable basis and jurisdiction mapping. Duplicate category,\ncomponent-within-category or line IDs fail closed. `line` scope rounds each\nline/component pair; `invoice` scope aggregates exact amounts per component and\nrounds once. Two 10-unit lines at 5 percent yield tax 2 versus 1 respectively.\nReturns `taxMinor` and component totals, deliberately without allocating rounded\ninvoice tax back to lines. Signed reversals use symmetric rounding, but mixed\npositive/negative lines may differ between rounding scopes.\n\n## Ordered compound tax with explicit allocation\n\n`calculateOrderedCostBillingTax` is a separate opt-in calculator on the same\nentry point. The additive calculator above, existing model/editor rounding and\nhistorical snapshots are unchanged. This helper neither infers regional rules\nnor persists policy. Applications must explicitly select approved tenant/regional\nsettings, preserve their accepted policy and result snapshots, and decide when a\nnew calculation is appropriate.\n\nSupply `lines` (`id`, signed safe-integer `amountMinor`, `category`), `categories`\n(`category`, `componentIds`) and ordered `components` (`id`, exact `percent`,\n`priorComponentIds`). Every component must explicitly supply `priorComponentIds`:\n`[]` means net-only; otherwise each ID must name a distinct earlier component.\nThe component basis on each eligible line is its net plus that line's allocated\ntax for exactly those prior components. A prior tax not applicable to that line\ncontributes zero. Category membership order does not control execution; the\nglobal component array does. A category's empty `componentIds` means exempt.\n\nChoose `roundingScope: 'line'` to round each eligible line/component pair\nhalf-away-from-zero. Invoice allocation options are forbidden in this mode,\nincluding an explicitly present `invoiceAllocation: undefined` property.\nChoose `roundingScope: 'invoice'` with the mandatory explicit\n`invoiceAllocation: 'signed-largest-remainder'` to round each component once\nover its eligible lines and distribute that rounded amount as follows:\n\n1. Calculate each eligible line's exact rational tax from its compound basis.\n2. Truncate each exact tax toward zero, retaining its signed fractional remainder.\n3. Round the exact component aggregate half-away-from-zero. Subtract the sum of\n   truncated line taxes to obtain the signed residual.\n4. For positive residual, assign one extra minor unit to each of the lines with\n   the largest signed remainders; for negative residual, subtract one unit from\n   each line with the smallest (most negative) remainders. Stop when conserved.\n   Ties use ascending JavaScript UTF-16 code-unit line ID order, never locale\n   collation or input order. A zero residual leaves every truncated tax unchanged.\n\nThis allocation is a caller-selected arithmetic convention, not a jurisdiction\ndefault or independent per-line rounding. It supports mixed signs and exact full\nreversal: keeping the same IDs/policy and negating all amounts negates every\nreturned basis and allocation. An individual line's allocation can change when\nother lines change; independently recalculating a subset or a partial reversal\ndoes not preserve the original invoice allocation. Consumers needing historical\npartial adjustments must use their accepted snapshot and explicit adjustment\npolicy. Mixed exact taxes `+0.8` and `-0.8` have zero aggregate and allocate\n`0, 0` under this convention.\n\nFor example, lines `a` and `b`, each net 10, both receive `first` at 5 percent.\nThe invoice tax is 1, allocated `a: 1, b: 0`. If only `a` receives `second` at\n100 percent with `priorComponentIds: ['first']`, its basis is 11 and its tax 11;\nthe total tax is 12. If only `b` receives `second`, its basis and tax are 10.\nNegating both original amounts allocates `first` as `a: -1, b: 0`; the second\ntax on `a` has basis and tax -11, total tax -12. At line scope the positive\nexample instead yields first tax 2 and total tax 13.\n\nThe result is `{ taxMinor, components }`. Components follow the supplied global\norder and each returns `{ id, taxMinor, lines }`, where eligible lines are\n`{ id, basisMinor, taxMinor }` in ascending code-unit ID order. Each component's\nline allocations sum exactly to its total. Components with no eligible lines\nreturn zero and `lines: []`; well-formed unused categories and components remain\nvalid for reusable policy. Exempt lines appear in no component allocation.\nRepeated calculations and input line/category/membership permutations produce\nidentical output. All arithmetic intermediates use BigInt; every returned basis,\nallocation, component tax and final tax must fit a safe integer, even when a\nlarger value would later cancel or a component has a zero rate.\n\nAll configuration is validated, including unused entries. Missing category\nmapping, unknown IDs, duplicate line/category/component/membership/prior IDs,\nforward/self references, missing arrays, malformed rates and unknown modes fail\nclosed. Rates use the same bounded decimal-string contract as the additive API.\nThe input is never mutated and the result holds no aliases to input objects.\n"
+    },
+    {
+      "path": "agents/contract-billing-schedules.md",
+      "module": "contract-billing-schedules",
+      "content": "# Contract milestone billing (#4074)\n\nUse the public Commerce `approveContractBillingSchedule`,\n`issueContractMilestoneInvoice`, `getContractBillingSchedule` and\n`allocateContractMilestones` exports for fixed-value milestone billing. These\ncommands own monetary capacity. The host owns construction scope, estimated cost,\napproval permissions, signed evidence, regional policy and UI.\n\nStart with an accepted, frozen customer `Order` or `Agreement`. The first schedule\nrequires `amendmentMinor: 0`, `expectedRevision: 0`, currency, explicit `basis:\n'net' | 'gross'`, `approvalEvidenceRef`, `taxPolicyEvidenceRef` and exact milestone\n`{ key, label, amountMinor }` entries. Their sum must equal the original Contract\nsubtotal for net basis or totalAmount for gross basis. There is no editable\nschedule override of the accepted Contract value.\n\nEach amendment supplies the current expected revision, a new request identity,\nan explicit signed `amendmentMinor`, approval evidence and the complete next\nschedule. Its ceiling is derived from the original frozen value plus all approved\namendments. Currency/basis cannot change. Already issued milestone keys, labels\nand amounts must remain unchanged. Prior revisions and original Contract money\nremain immutable. Unissued milestones can be rescheduled through an explicitly\napproved revision. Net capacity is not a gross ceiling: each invoice's tax must\nalso be explicitly approved under the versioned policy.\n\n`allocateContractMilestones(totalMinor, weights)` accepts positive integer\nrelative weights. All nonfinal shares truncate exact rational arithmetic; the\nfinal entry receives the exact remainder. For example 100 with weights [1,1,1]\nreturns [33,33,34]. Zero amounts are allowed; negative/unsafe money and nonpositive\nweights reject. The helper chooses no tax policy or commercial percentages.\n\nPrepare a normal canonical draft Invoice and real line items through the public\nCommerce collections. Draft preparation consumes no capacity; an unissued draft may be cancelled\nwithout a claim. Then call:\n\n```ts\nconst claim = await issueContractMilestoneInvoice({\n  db, tenantId, contractId, requestId: 'issue:start:v1',\n  revision: 1, milestoneKey: 'start', invoiceId,\n  approvedMoney: { netMinor: 4000, taxMinor: 200, grossMinor: 4200 },\n  invoiceApprovalEvidenceRef: 'approved-invoice:123',\n});\n```\n\nThe command checks same tenant/customer/currency/Contract, derives current line\nmoney, verifies the exact approved net/tax/gross and schedule amount, freezes the\ninvoice and records the claim atomically. Tax-policy evidence is a host-owned\nreviewed version reference, not an instruction to infer tax rates. Preserve the\napproval's policy and original evidence in the host. Ordinary issue against a\nscheduled Contract is refused, including direct creation in a non-draft state.\nExisting issued contract invoices prevent adopting a schedule retroactively.\n\nThe explicit capacity policy is `issued-consumed`: cancellation, credits,\nwrite-offs, payments, retention and refunds never reopen a claimed milestone.\nCredits correct the canonical receivable and settlement continues through existing\nPayment/PaymentAllocation facilities. Unapplied payments remain the deposit cash\nauthority. A replacement billing entitlement requires an explicit approved\namendment; this API does not infer that a credit authorizes re-billing. Applications\nmust explain that policy rather than present a hidden re-bill action. Issued\nclaims remain readable after later amendments and cancellations.\n\nEvery mutation requires the active tenant context and uses the tenant money\nserialization barrier on the exact parent transaction executor. Identical request\nreplay returns the original evidence; a changed payload, stale revision or second\nclaim rejects. A parent rollback reverses both invoice issue and schedule claim.\nA detached read DTO cannot modify persisted state. Ordinary Contract writes and\ndeletes cannot erase schedule history. Host authorization precedes these commands;\nnone is exposed as an unauthenticated generated mutation.\n"
+    },
+    {
+      "path": "agents/customer-funds.md",
+      "module": "customer-funds",
+      "content": "# Customer advances and unallocated cash\n\nThe public `recordCustomerFunds`, `allocateCustomerFunds`, `refundCustomerFunds`,\n`reverseCustomerFundsAllocation` and `getCustomerFundsFacts` commands reuse\nPayment, PaymentAllocation and smrt-ledgers journals. They do not create invoice\nrevenue, issue credit notes, transmit money to a bank or call a provider.\nApplications authorize each command and supply human/source evidence.\n\nA receipt requires an explicit immutable policy version:\n\n- `mode`: `unapplied-ar` or `deposit-liability`.\n- `taxTiming: 'invoice-tax-point'`: the caller has explicitly reviewed that tax\n  belongs on the eventual invoice. This is the only supported timing. The API\n  does not assume that every jurisdiction treats deposits as untaxed; other\n  timing policies are rejected and need a separate supported accounting model.\n- `releaseEligibility`: `any-issued-invoice` or `final-invoice-only`.\n- Distinct cash and receivables asset accounts, plus a liability account only\n  for liability mode. Every account must be active in the same tenant chart.\n\nLedgers currently has no separate Ledger entity or currency-restricted Account\nfield. The ledger boundary is its tenant-owned chart; currency is explicit on\nthis receipt and every journal entry. The legacy `RecordPaymentOptions.ledgerId`\nis unused by existing Payment settlement. These commands neither pretend it\nvalidates an independent ledger nor invent account metadata conventions.\n\n| Operation | Unapplied AR | Deposit liability |\n| --- | --- | --- |\n| Receipt | DR cash / CR AR | DR cash / CR customer liability |\n| Application | Existing settlement allocation | DR customer liability / CR AR |\n| Unallocated refund | DR AR / CR cash | DR customer liability / CR cash |\n| Application reversal | Reverse settlement allocation | DR AR / CR customer liability |\n\nAll amounts are positive safe integer minor units. Available capacity is exactly\n`received - active applications - settled source-linked refunds`. A refund is a\npositive outgoing Payment with immutable source-receipt lineage; it is not an\ninvoice credit refund. Reversal retains the original application and appends an\ninverse operation and journal, removing only the active settlement row. An issued\ninvoice credit or credit refund blocks application reversal so previously spent\ncash cannot become refundable a second time. Resolve that invoice correction\nthrough its own authority first.\n\nEach request carries `effectiveOn` (calendar date), `evidenceRef`, `actorId` and a\nstable `requestId`. Effective dates are distinct from recording timestamps and\nmust be chronological within a receipt's movements. Receipt/refund `paidAt` and\njournal dates use the explicitly supplied effective date. Exact replays return\ncurrent conserved facts; changing the request payload fails. Refund/application\nraces serialize on the tenant money boundary and receipt revision. Caller-owned\ntransactions include the payment, journals, allocation, status and audit evidence.\n\nApplication requires a matching issued invoice, customer, currency, optional\nsales contract and actual `moneySnapshotId`. `release` also names the frozen\nreceipt policy version and the host's immutable invoice-approval evidence. Under\nfinal-only policy, the host must verify and attest `kind: 'final-invoice'` from\nthat frozen approval. This is an application authorization responsibility, not a\nuser-supplied checkbox or inference from invoice numbering. The generic library\nchecks the attestation shape and exact canonical monetary snapshot; it does not\nknow construction milestone/finality rules.\n\n`Payment.customerFundsJson` is command-owned. Ordinary saves, deletes,\nPaymentAllocation create/update/delete, collection allocation helpers, payment\nintent settlement and supplier payouts cannot repurpose managed advances or\nbypass required journal entries. Managed refunds cannot be allocated to invoice\ncredits. `getUnallocatedFromPayment` subtracts managed refunds and requires the\npersisted receipt amount. Direct SQL and administrative ledger mutations remain\noutside this domain authority; facts refuse missing/voided journal evidence.\n\n```ts\nawait withTenant({ tenantId }, async () => {\n  const received = await recordCustomerFunds({\n    db, tenantId, customerId, currency: 'CAD', amountMinor: 10000,\n    method: PaymentMethod.BANK_TRANSFER, requestId: receiptRequestId,\n    effectiveOn: '2026-10-01', evidenceRef: bankReceiptRef, actorId,\n    policy: {\n      version: reviewedPolicyVersion, mode: 'deposit-liability',\n      taxTiming: 'invoice-tax-point', releaseEligibility: 'final-invoice-only',\n      cashAccountId, receivablesAccountId, liabilityAccountId,\n    },\n  });\n  await allocateCustomerFunds({\n    db, tenantId, paymentId: received.paymentId, invoiceId, amountMinor: 8000,\n    requestId: applicationRequestId, effectiveOn: '2026-10-10',\n    evidenceRef: applicationEvidenceRef, actorId,\n    release: {\n      kind: 'final-invoice', invoiceSnapshotId,\n      approvalEvidenceRef: frozenFinalInvoiceApprovalRef,\n      policyVersion: reviewedPolicyVersion,\n    },\n  });\n});\n```\n\nNative `customer-funds.test.ts` and `customer-funds.optional.test.ts` prove exact\njournals, both modes, direct-path protections, dates, finality evidence,\nconservation, invoice-credit interaction, retries, caller rollback and a real\nPostgreSQL post-journal write fault plus refund/application race. Run PostgreSQL\nthrough the standard managed database wrapper; never use an application's schema.\n"
+    },
+    {
+      "path": "agents/observed-purchase-prices.md",
+      "module": "observed-purchase-prices",
+      "content": "# Incomplete observed purchase prices\n\n`recordPurchasePriceObservation` records a supplier quote or purchase-order source\ninstrument when the source does not establish every monetary total. Each of\n`netMinor`, `taxMinor`, and `grossMinor` is an explicit safe nonnegative integer\nor `null`. Zero is a known value; null is unknown. At least one amount is known.\nThe host explicitly interprets whether a source amount is net or gross. The\ncommand neither derives absent tax nor uses current tax rates.\n\nThe public `PurchasePriceObservation` is separate from `Contract`. Its readback\nhas `monetaryAggregate: null`, the complete original snapshot, and an optional\ncompletion link. It cannot appear in ordinary purchase tax reports or be\naccepted as a calculated Contract. Source `selected`, `approved`, or other\nstatus text remains original evidence and grants no current approval.\n\nSource identity is `(tenant, namespace, kind, sourceKey)`. Exact replay returns\nthe original object. Changed evidence or request identity requires a new source\nrevision; it cannot rewrite the original. Concrete source lines retain their\nkeys and exact quantity/rate text, even when those texts do not explain the\nsupplier's observed amount. They are evidence, not calculator inputs.\n\n`completePurchasePriceObservation` requires separate reviewed evidence and the\nexisting complete `ReceivedPurchaseMoneyFacts` contract. It preserves every\nknown original header amount and every fully known source-line total. When\ncomplete line detail is supplied, identities, descriptions, quantity/rate text,\nand known amounts must also match. Header-only completion does not allocate tax\nor invent source line amounts: the original lines remain in the observation.\nThe command atomically creates a **draft** received SupplierQuote or\nPurchaseOrder and appends its link. The host separately authorizes any later\nacceptance. This is completion of unknown facts, not a negotiated price change.\n\nAll commands require the matching active tenant. The host authorizes the human\noperation and supplies the owning executor. The tenant money barrier serializes\nrecording/completion and participates in caller rollback. Ordinary model saves,\ncollection creates, and deletes are rejected. No original journal or provider\nwrite is created. The existing received-purchase tax-classification requirements\napply if a completed purchase order is subsequently accepted and reported.\n"
+    },
+    {
+      "path": "agents/received-sales-contract-money.md",
+      "module": "received-sales-contract-money",
+      "content": "# Received sales agreement money\n\n`recordReceivedSalesContractMoney({ db, tenantId, contractId, requestId,\nevidenceRef, facts })` records explicitly supplied complete original monetary\nfacts on an empty draft `Order` or `Agreement` with a same-tenant customer.\nIt reuses the public complete received-money validator: safe nonnegative minor\nunits, exact net plus tax equals gross, known zero distinct from unknown tax\nclassification, and either header-only evidence or real complete source lines.\nNo quantity, price, tax rate, line allocation or current tax policy is invented.\nSales tax components must retain `recoverableMinor: null`; purchase recovery does\nnot apply. Supplier quote lineage is not accepted on this command.\n\n`getReceivedSalesContractMoney(contract)` returns the immutable evidence or null.\nSales-named facts, snapshot and input types are public. The snapshot shares the\nexisting version-1 received-money representation and keeps `sourceQuote: null`.\nThe legacy `receivedPurchaseMoneyJson` storage name remains for schema compatibility;\napplications must use commands rather than writing that field.\n\nThe host authorizes the review and binds its immutable original source separately\nto this newly completed authority. Merely importing a source label such as signed\nor approved does not grant current acceptance. Normal acceptance freezes the\ncomplete money snapshot and permits the existing approved billing-schedule\ncommands. Issued invoices remain separate actual financial instruments.\n\nRecording or accepting an agreement does not recognize revenue, create an AR or\ntax journal, or add incurred tax-report facts. Only the applicable invoice or\npurchase accounting authority contributes those facts. Incomplete original\nagreement totals remain host evidence until reviewed complete totals are supplied.\n\nThe command uses the caller executor and active tenant, locks the parent, rejects\ncalculated lines and frozen drafts, and preserves exact retry identity. Ordinary\nmoney mutations and deletion are guarded. Replays with changed evidence or facts\nrequire a separate contract revision. Competing requests cannot overwrite the\nfirst recorded authority; outer transaction rollback includes the entire record.\n\nThe customer is frozen as soon as original money is recorded, including while\nthe agreement or order is still a draft. Reassignment requires a new contract;\nacceptance and retry preserve the original customer and monetary evidence.\n"
     }
   ],
   "recipes": [
@@ -19810,7 +21560,7 @@
       ],
       "nav": [
         {
-          "label": "Agreements",
+          "label": "General agreements",
           "model": "@happyvertical/smrt-commerce:Agreement",
           "icon": "fileText",
           "description": "Signed deals and terms with your customers, in one place."
@@ -20186,6 +21936,9 @@
       "options": {
         "@happyvertical/smrt-commerce:Invoice": {
           "fields": {
+            "historicalSourceKeyHash": {
+              "visibility": "hidden"
+            },
             "providerTaxAmount": {
               "visibility": "hidden"
             },