@happyvertical/smrt-commerce 0.55.24 → 0.56.0

package/dist/smrt-knowledge.json

@@ -3,19 +3,20 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-commerce",
-  "packageVersion": "0.55.24",
+  "packageVersion": "0.56.0",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "5fecd03ae3b2033ab017298d7beef3d4d38b2069d60f169e372c1f7e14ca8338",
-    "packageJson": "ba52e7d3b68131242e425cd105318d8ea47f9371d464e56c7c633ed03ad89719",
-    "agents": "1ec9ceb9d4380f1f239051a6726afbb2afe31ce0485498b8e40afc28aeb76356",
+    "manifest": "7b16744246ab3b23324644c7ceabbbebc4bea86c068ef7d89fe22976f6afde98",
+    "packageJson": "b5f10112111ac6b147dc07796d44b84372ea1f3766bae49b6b127da3bcf8f027",
+    "agents": "856b53999561b37edadaf7510d3eeadd56c95e5c5db092e255e603c831aa52a9",
     "moduleDoc:agents/customer-vendor-ui.md": "744fb88c23ad05e7fd953edc2598e7c13f15f0ffd69c9cba70dd3e0668ae17f8",
+    "moduleDoc:README.md": "eee4fdd5600e46b152bb5a3ae09fcb4256a9e9ebbde2000cfea90f060ed8914e",
     "moduleDoc:agents/invoice-quantity.md": "bc3b617d4fb8cc87511763b281283107557ba64795e64522193ef967a3715d32",
     "moduleDoc:agents/payment-allocations.md": "46c0b921f0e40060cd1caec2dcefb01ed6612e31e4bf220a1a0b61e4e2a58212",
     "moduleDoc:agents/commercial-ui.md": "308729a481c82903d06837e7052c04509a92cf17d17345f71dce88d8d42d0431",
-    "moduleDoc:agents/quote-ui.md": "514568e4e7815c47113627ac044a1f31a6933377b3f6c70f5d54b2508d94200c",
-    "moduleDoc:agents/purchasing-ui.md": "c7d633c5ba45078c51f4066f68d90112cd748ac089ac34d209f9bf025739589f",
+    "moduleDoc:agents/quote-ui.md": "9d1faaa12f39e330294693f5309d9766c593dc0f7ced9e8b1dcaf5c81b066205",
+    "moduleDoc:agents/purchasing-ui.md": "d2b413009d466f3320934adf1e30ffbb7278138b859df69635e7c1f77efbbd1c",
     "moduleDoc:agents/cost-billing.md": "e60e6b7285962464e9bbc35ce259f7e99a81f6c9c39ae5855cdd0a34093d8d47"
   },
   "exports": [
@@ -3815,6 +3816,84 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "PurchaseContractCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:PurchaseContractCollection",
+      "collection": "contracts",
+      "description": "Read supplier-side contracts across every purchase STI subtype.",
+      "tableName": "contracts",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByVendor"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findByVendor",
+          "async": true,
+          "params": [
+            "vendorId: string"
+          ],
+          "returns": "Promise<PurchaseContract[]>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "findByVendor",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContractCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SalesContractCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:SalesContractCollection",
+      "collection": "contracts",
+      "description": "Read customer-side contracts across every sales STI subtype.",
+      "tableName": "contracts",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByCustomer"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findByCustomer",
+          "async": true,
+          "params": [
+            "customerId: string"
+          ],
+          "returns": "Promise<SalesContract[]>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "findByCustomer",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:SalesContractCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "VendorCollection",
       "qualifiedName": "@happyvertical/smrt-commerce:VendorCollection",
@@ -4075,22 +4154,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -4177,22 +4240,7 @@
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
         }
       ],
-      "relationships": [
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID"
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID"
-        }
-      ],
+      "relationships": [],
       "methods": [
         "initialize",
         "isAccepted",
@@ -4304,64 +4352,671 @@
           "objectName": "@happyvertical/smrt-commerce:Contract"
         },
         {
-          "kind": "cli",
-          "name": "contract_update",
-          "operation": "update",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "kind": "cli",
+          "name": "contract_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "cli",
+          "name": "contract_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "cli",
+          "name": "contract_isDraft",
+          "operation": "isDraft",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "cli",
+          "name": "contract_isAccepted",
+          "operation": "isAccepted",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "cli",
+          "name": "contract_isCompleted",
+          "operation": "isCompleted",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "cli",
+          "name": "contract_isExpired",
+          "operation": "isExpired",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "cli",
+          "name": "contract_isOverdue",
+          "operation": "isOverdue",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "cli",
+          "name": "contract_recalculateTotals",
+          "operation": "recalculateTotals",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "mcp",
+          "name": "contract_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "mcp",
+          "name": "contract_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "initialize",
+          "code": "lifecycle-method",
+          "reason": "`initialize` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "api",
+          "operation": "isAccepted",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "api",
+          "operation": "isCompleted",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "api",
+          "operation": "isDraft",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "api",
+          "operation": "isExpired",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "api",
+          "operation": "isOverdue",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "api",
+          "operation": "recalculateTotals",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-commerce:Contract"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SalesContract",
+      "qualifiedName": "@happyvertical/smrt-commerce:SalesContract",
+      "collection": "contracts",
+      "description": "Customer-side contracts, including orders, estimates, and licenses.",
+      "tableName": "contracts",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "Contract",
+      "fields": [
+        {
+          "name": "created_at",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "updated_at",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "contractType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
+        },
+        {
+          "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": "totalAmount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0,
+          "description": "The full amount, tax included."
+        },
+        {
+          "name": "currency",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "USD",
+          "description": "The currency of the amounts."
+        },
+        {
+          "name": "issueDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "The date it was issued or placed."
+        },
+        {
+          "name": "dueDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "The date payment or delivery is due."
+        },
+        {
+          "name": "expiryDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "The last day the price or offer is good for."
+        },
+        {
+          "name": "reference",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "Your own number or note for finding this later, such as a purchase order or quote number."
+        },
+        {
+          "name": "notes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "Anything worth remembering about this."
+        },
+        {
+          "name": "terms",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "The conditions agreed, such as deposits, payment or delivery conditions."
+        },
+        {
+          "name": "channelId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "Where it came from, for example your shop, a marketplace or a phone call."
+        },
+        {
+          "name": "customerId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Customer",
+          "columnType": "UUID",
+          "description": "The customer a sales order or agreement is for."
+        }
+      ],
+      "relationships": [
+        {
+          "name": "customerId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Customer",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "initialize",
+        "isAccepted",
+        "isCompleted",
+        "isDraft",
+        "isExpired",
+        "isOverdue",
+        "recalculateTotals",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "initialize",
+          "async": true,
+          "returns": "Promise<this>"
+        },
+        {
+          "name": "isAccepted",
+          "returns": "boolean"
+        },
+        {
+          "name": "isCompleted",
+          "returns": "boolean"
+        },
+        {
+          "name": "isDraft",
+          "returns": "boolean"
+        },
+        {
+          "name": "isExpired",
+          "returns": "boolean"
+        },
+        {
+          "name": "isOverdue",
+          "returns": "boolean"
+        },
+        {
+          "name": "recalculateTotals",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "tableStrategy": "sti",
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "contracts.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract",
+          "path": "/contracts",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "contracts.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract",
+          "path": "/contracts/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "salescontract_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "cli",
+          "name": "salescontract_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "mcp",
+          "name": "salescontract_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "mcp",
+          "name": "salescontract_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "initialize",
+          "code": "lifecycle-method",
+          "reason": "`initialize` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "api",
+          "operation": "isAccepted",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "api",
+          "operation": "isCompleted",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "api",
+          "operation": "isDraft",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "api",
+          "operation": "isExpired",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "api",
+          "operation": "isOverdue",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "api",
+          "operation": "recalculateTotals",
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-commerce:SalesContract"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "PurchaseContract",
+      "qualifiedName": "@happyvertical/smrt-commerce:PurchaseContract",
+      "collection": "contracts",
+      "description": "Supplier-side contracts, including purchase and production orders.",
+      "tableName": "contracts",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "Contract",
+      "fields": [
+        {
+          "name": "created_at",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "updated_at",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "contractType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
+        },
+        {
+          "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": "totalAmount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "default": 0,
+          "description": "The full amount, tax included."
+        },
+        {
+          "name": "currency",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "USD",
+          "description": "The currency of the amounts."
+        },
+        {
+          "name": "issueDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "The date it was issued or placed."
+        },
+        {
+          "name": "dueDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "The date payment or delivery is due."
+        },
+        {
+          "name": "expiryDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "The last day the price or offer is good for."
+        },
+        {
+          "name": "reference",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "Your own number or note for finding this later, such as a purchase order or quote number."
+        },
+        {
+          "name": "notes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "Anything worth remembering about this."
+        },
+        {
+          "name": "terms",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "The conditions agreed, such as deposits, payment or delivery conditions."
+        },
+        {
+          "name": "channelId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "Where it came from, for example your shop, a marketplace or a phone call."
+        },
+        {
+          "name": "vendorId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Vendor",
+          "columnType": "UUID",
+          "description": "The vendor a purchase order is placed with."
+        }
+      ],
+      "relationships": [
+        {
+          "name": "vendorId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Vendor",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "initialize",
+        "isAccepted",
+        "isCompleted",
+        "isDraft",
+        "isExpired",
+        "isOverdue",
+        "recalculateTotals",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "initialize",
+          "async": true,
+          "returns": "Promise<this>"
+        },
+        {
+          "name": "isAccepted",
+          "returns": "boolean"
+        },
+        {
+          "name": "isCompleted",
+          "returns": "boolean"
+        },
+        {
+          "name": "isDraft",
+          "returns": "boolean"
         },
         {
-          "kind": "cli",
-          "name": "contract_delete",
-          "operation": "delete",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "name": "isExpired",
+          "returns": "boolean"
         },
         {
-          "kind": "cli",
-          "name": "contract_isDraft",
-          "operation": "isDraft",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "name": "isOverdue",
+          "returns": "boolean"
         },
         {
-          "kind": "cli",
-          "name": "contract_isAccepted",
-          "operation": "isAccepted",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "name": "recalculateTotals",
+          "async": true,
+          "returns": "Promise<void>"
         },
         {
-          "kind": "cli",
-          "name": "contract_isCompleted",
-          "operation": "isCompleted",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "tableStrategy": "sti",
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "contracts.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract",
+          "path": "/contracts",
+          "method": "GET"
         },
         {
-          "kind": "cli",
-          "name": "contract_isExpired",
-          "operation": "isExpired",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "kind": "api",
+          "name": "contracts.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract",
+          "path": "/contracts/[id]",
+          "method": "GET"
         },
         {
           "kind": "cli",
-          "name": "contract_isOverdue",
-          "operation": "isOverdue",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "name": "purchasecontract_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "cli",
-          "name": "contract_recalculateTotals",
-          "operation": "recalculateTotals",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "name": "purchasecontract_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "mcp",
-          "name": "contract_list",
+          "name": "purchasecontract_list",
           "operation": "list",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "mcp",
-          "name": "contract_get",
+          "name": "purchasecontract_get",
           "operation": "get",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         }
       ],
       "withheldSurfaces": [
@@ -4370,56 +5025,56 @@
           "operation": "initialize",
           "code": "lifecycle-method",
           "reason": "`initialize` is a framework lifecycle method, not a distinct operation",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "api",
           "operation": "isAccepted",
-          "code": "not-included",
-          "reason": "not listed in api.include",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "api",
           "operation": "isCompleted",
-          "code": "not-included",
-          "reason": "not listed in api.include",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "api",
           "operation": "isDraft",
-          "code": "not-included",
-          "reason": "not listed in api.include",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "api",
           "operation": "isExpired",
-          "code": "not-included",
-          "reason": "not listed in api.include",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "api",
           "operation": "isOverdue",
-          "code": "not-included",
-          "reason": "not listed in api.include",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "api",
           "operation": "recalculateTotals",
-          "code": "not-included",
-          "reason": "not listed in api.include",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "code": "excluded",
+          "reason": "listed in api.exclude",
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         },
         {
           "kind": "api",
           "operation": "save",
           "code": "lifecycle-method",
           "reason": "`save` is a framework lifecycle method, not a distinct operation",
-          "objectName": "@happyvertical/smrt-commerce:Contract"
+          "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
         }
       ],
       "relationshipFeatures": [
@@ -4436,7 +5091,7 @@
       "description": "Quote or proposal for a customer",
       "tableName": "contracts",
       "packageName": "@happyvertical/smrt-commerce",
-      "extends": "Contract",
+      "extends": "SalesContract",
       "fields": [
         {
           "name": "created_at",
@@ -4460,8 +5115,7 @@
           "name": "contractType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+          "columnType": "TEXT"
         },
         {
           "name": "status",
@@ -4470,22 +5124,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -4570,21 +5208,21 @@
           "columnType": "TEXT",
           "default": "",
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
-        }
-      ],
-      "relationships": [
+        },
         {
           "name": "customerId",
           "type": "foreignKey",
-          "required": false,
+          "required": true,
           "related": "Customer",
           "columnType": "UUID"
-        },
+        }
+      ],
+      "relationships": [
         {
-          "name": "vendorId",
+          "name": "customerId",
           "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
+          "required": true,
+          "related": "Customer",
           "columnType": "UUID"
         }
       ],
@@ -4893,7 +5531,7 @@
       "description": "Customer purchase order",
       "tableName": "contracts",
       "packageName": "@happyvertical/smrt-commerce",
-      "extends": "Contract",
+      "extends": "SalesContract",
       "fields": [
         {
           "name": "created_at",
@@ -4917,8 +5555,7 @@
           "name": "contractType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+          "columnType": "TEXT"
         },
         {
           "name": "status",
@@ -4927,22 +5564,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -5027,21 +5648,21 @@
           "columnType": "TEXT",
           "default": "",
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
-        }
-      ],
-      "relationships": [
+        },
         {
           "name": "customerId",
           "type": "foreignKey",
-          "required": false,
+          "required": true,
           "related": "Customer",
           "columnType": "UUID"
-        },
+        }
+      ],
+      "relationships": [
         {
-          "name": "vendorId",
+          "name": "customerId",
           "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
+          "required": true,
+          "related": "Customer",
           "columnType": "UUID"
         }
       ],
@@ -5350,7 +5971,7 @@
       "description": "Rental or lease agreement",
       "tableName": "contracts",
       "packageName": "@happyvertical/smrt-commerce",
-      "extends": "Contract",
+      "extends": "SalesContract",
       "fields": [
         {
           "name": "created_at",
@@ -5374,8 +5995,7 @@
           "name": "contractType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+          "columnType": "TEXT"
         },
         {
           "name": "status",
@@ -5384,22 +6004,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -5484,21 +6088,21 @@
           "columnType": "TEXT",
           "default": "",
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
-        }
-      ],
-      "relationships": [
+        },
         {
           "name": "customerId",
           "type": "foreignKey",
-          "required": false,
+          "required": true,
           "related": "Customer",
           "columnType": "UUID"
-        },
+        }
+      ],
+      "relationships": [
         {
-          "name": "vendorId",
+          "name": "customerId",
           "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
+          "required": true,
+          "related": "Customer",
           "columnType": "UUID"
         }
       ],
@@ -5807,7 +6411,7 @@
       "description": "Service or maintenance agreement",
       "tableName": "contracts",
       "packageName": "@happyvertical/smrt-commerce",
-      "extends": "Contract",
+      "extends": "SalesContract",
       "fields": [
         {
           "name": "created_at",
@@ -5831,8 +6435,7 @@
           "name": "contractType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+          "columnType": "TEXT"
         },
         {
           "name": "status",
@@ -5841,22 +6444,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -5941,21 +6528,21 @@
           "columnType": "TEXT",
           "default": "",
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
-        }
-      ],
-      "relationships": [
+        },
         {
           "name": "customerId",
           "type": "foreignKey",
-          "required": false,
+          "required": true,
           "related": "Customer",
           "columnType": "UUID"
-        },
+        }
+      ],
+      "relationships": [
         {
-          "name": "vendorId",
+          "name": "customerId",
           "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
+          "required": true,
+          "related": "Customer",
           "columnType": "UUID"
         }
       ],
@@ -6264,7 +6851,7 @@
       "description": "Order sent to vendor/supplier",
       "tableName": "contracts",
       "packageName": "@happyvertical/smrt-commerce",
-      "extends": "Contract",
+      "extends": "PurchaseContract",
       "fields": [
         {
           "name": "created_at",
@@ -6288,8 +6875,7 @@
           "name": "contractType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+          "columnType": "TEXT"
         },
         {
           "name": "status",
@@ -6298,22 +6884,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -6399,6 +6969,13 @@
           "default": "",
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
         },
+        {
+          "name": "vendorId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Vendor",
+          "columnType": "UUID"
+        },
         {
           "name": "expectedDate",
           "type": "meta",
@@ -6415,17 +6992,10 @@
         }
       ],
       "relationships": [
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID"
-        },
         {
           "name": "vendorId",
           "type": "foreignKey",
-          "required": false,
+          "required": true,
           "related": "Vendor",
           "columnType": "UUID"
         }
@@ -6735,7 +7305,7 @@
       "description": "B2B order placed by a wholesale customer.",
       "tableName": "contracts",
       "packageName": "@happyvertical/smrt-commerce",
-      "extends": "Contract",
+      "extends": "SalesContract",
       "fields": [
         {
           "name": "created_at",
@@ -6759,8 +7329,7 @@
           "name": "contractType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+          "columnType": "TEXT"
         },
         {
           "name": "status",
@@ -6769,22 +7338,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -6869,21 +7422,21 @@
           "columnType": "TEXT",
           "default": "",
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
-        }
-      ],
-      "relationships": [
+        },
         {
           "name": "customerId",
           "type": "foreignKey",
-          "required": false,
+          "required": true,
           "related": "Customer",
           "columnType": "UUID"
-        },
+        }
+      ],
+      "relationships": [
         {
-          "name": "vendorId",
+          "name": "customerId",
           "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
+          "required": true,
+          "related": "Customer",
           "columnType": "UUID"
         }
       ],
@@ -7192,7 +7745,7 @@
       "description": "Instruction to commission goods from an internal or external factory.",
       "tableName": "contracts",
       "packageName": "@happyvertical/smrt-commerce",
-      "extends": "Contract",
+      "extends": "PurchaseContract",
       "fields": [
         {
           "name": "created_at",
@@ -7216,8 +7769,7 @@
           "name": "contractType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+          "columnType": "TEXT"
         },
         {
           "name": "status",
@@ -7226,22 +7778,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -7327,6 +7863,14 @@
           "default": "",
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
         },
+        {
+          "name": "vendorId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Vendor",
+          "columnType": "UUID",
+          "description": "The vendor a purchase order is placed with."
+        },
         {
           "name": "productId",
           "type": "meta",
@@ -7341,13 +7885,6 @@
         }
       ],
       "relationships": [
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID"
-        },
         {
           "name": "vendorId",
           "type": "foreignKey",
@@ -7661,7 +8198,7 @@
       "description": "Transient order-in-progress for a shopper.",
       "tableName": "contracts",
       "packageName": "@happyvertical/smrt-commerce",
-      "extends": "Contract",
+      "extends": "SalesContract",
       "fields": [
         {
           "name": "created_at",
@@ -7685,8 +8222,7 @@
           "name": "contractType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+          "columnType": "TEXT"
         },
         {
           "name": "status",
@@ -7695,22 +8231,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -7795,21 +8315,22 @@
           "columnType": "TEXT",
           "default": "",
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
-        }
-      ],
-      "relationships": [
+        },
         {
           "name": "customerId",
           "type": "foreignKey",
           "required": false,
           "related": "Customer",
-          "columnType": "UUID"
-        },
+          "columnType": "UUID",
+          "description": "The customer a sales order or agreement is for."
+        }
+      ],
+      "relationships": [
         {
-          "name": "vendorId",
+          "name": "customerId",
           "type": "foreignKey",
           "required": false,
-          "related": "Vendor",
+          "related": "Customer",
           "columnType": "UUID"
         }
       ],
@@ -8118,7 +8639,7 @@
       "description": "Industry-neutral licensing primitive.",
       "tableName": "contracts",
       "packageName": "@happyvertical/smrt-commerce",
-      "extends": "Contract",
+      "extends": "SalesContract",
       "fields": [
         {
           "name": "created_at",
@@ -8142,8 +8663,7 @@
           "name": "contractType",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "description": "The kind of contract: order, estimate, lease, agreement and so on."
+          "columnType": "TEXT"
         },
         {
           "name": "status",
@@ -8152,22 +8672,6 @@
           "columnType": "TEXT",
           "description": "Where the order or agreement stands, for example draft, sent, accepted or completed."
         },
-        {
-          "name": "customerId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Customer",
-          "columnType": "UUID",
-          "description": "The customer a sales order or agreement is for."
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID",
-          "description": "The vendor a purchase order is placed with."
-        },
         {
           "name": "subtotal",
           "type": "integer",
@@ -8253,6 +8757,14 @@
           "default": "",
           "description": "Where it came from, for example your shop, a marketplace or a phone call."
         },
+        {
+          "name": "customerId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Customer",
+          "columnType": "UUID",
+          "description": "The customer a sales order or agreement is for."
+        },
         {
           "name": "skuId",
           "type": "meta",
@@ -8351,13 +8863,6 @@
           "required": false,
           "related": "Customer",
           "columnType": "UUID"
-        },
-        {
-          "name": "vendorId",
-          "type": "foreignKey",
-          "required": false,
-          "related": "Vendor",
-          "columnType": "UUID"
         }
       ],
       "methods": [
@@ -9332,7 +9837,7 @@
           "name": "contractId",
           "type": "foreignKey",
           "required": false,
-          "related": "Contract",
+          "related": "SalesContract",
           "columnType": "UUID",
           "description": "The order being fulfilled."
         },
@@ -9406,7 +9911,7 @@
           "name": "contractId",
           "type": "foreignKey",
           "required": false,
-          "related": "Contract",
+          "related": "SalesContract",
           "columnType": "UUID"
         }
       ],
@@ -9857,7 +10362,7 @@
           "name": "contractId",
           "type": "foreignKey",
           "required": false,
-          "related": "Contract",
+          "related": "SalesContract",
           "columnType": "UUID",
           "description": "The order or agreement this invoice bills for, if any."
         },
@@ -10061,7 +10566,7 @@
           "name": "contractId",
           "type": "foreignKey",
           "required": false,
-          "related": "Contract",
+          "related": "SalesContract",
           "columnType": "UUID"
         },
         {
@@ -10901,7 +11406,7 @@
           "name": "contractId",
           "type": "foreignKey",
           "required": false,
-          "related": "Contract",
+          "related": "SalesContract",
           "columnType": "UUID",
           "description": "The order or agreement this payment is for, if any."
         },
@@ -11048,7 +11553,7 @@
           "name": "contractId",
           "type": "foreignKey",
           "required": false,
-          "related": "Contract",
+          "related": "SalesContract",
           "columnType": "UUID"
         },
         {
@@ -16581,6 +17086,86 @@
       "operation": "get",
       "objectName": "@happyvertical/smrt-commerce:Contract"
     },
+    {
+      "kind": "api",
+      "name": "contracts.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:SalesContract",
+      "path": "/contracts",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "contracts.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:SalesContract",
+      "path": "/contracts/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "salescontract_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:SalesContract"
+    },
+    {
+      "kind": "cli",
+      "name": "salescontract_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:SalesContract"
+    },
+    {
+      "kind": "mcp",
+      "name": "salescontract_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:SalesContract"
+    },
+    {
+      "kind": "mcp",
+      "name": "salescontract_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:SalesContract"
+    },
+    {
+      "kind": "api",
+      "name": "contracts.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:PurchaseContract",
+      "path": "/contracts",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "contracts.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:PurchaseContract",
+      "path": "/contracts/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "purchasecontract_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
+    },
+    {
+      "kind": "cli",
+      "name": "purchasecontract_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
+    },
+    {
+      "kind": "mcp",
+      "name": "purchasecontract_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
+    },
+    {
+      "kind": "mcp",
+      "name": "purchasecontract_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-commerce:PurchaseContract"
+    },
     {
       "kind": "api",
       "name": "contracts.list",
@@ -19868,20 +20453,25 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 37,
+    "foreignKeyFields": 28,
     "crossPackageRefFields": 14,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 162
+    "uuidColumns": 178
   },
-  "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** (STI base → Estimate, Order, Lease, Agreement, PurchaseOrder, WholesaleOrder, ProductionOrder, Cart, LicenseSale): 9 contract types sharing one table. Carries `channelId` (open-ended string — `dtc-web`, `wholesale-b2b`, `pos-store-N`, etc.) so the same model serves DTC checkout, B2B portals, and POS.\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; editor-mode recovery and existing-column migration are 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.\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- **`Invoice.providerTaxAmount`** is added to line-item tax; it is\n  server-managed (not API-writable). `toAccountingInput()` 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- `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- **Currency is integer minor units** (cents, satoshis) — `$19.99` is `1999`, like affiliates. Money is exact, so money fields initialize `= 0`, never `= 0.0`: the integer literal is what maps them to INTEGER columns (BIGINT on fresh PostgreSQL/DuckDB databases). Writing a fractional major-unit value is the bug — the model rejects it via `assertIntegerMinorUnits` on `Invoice`/`Payment`/`PaymentAllocation`/`Payout`/`Contract` before the database sees it, because PostgreSQL would reject it with `22P02` while SQLite's affinity silently stores it. `pnpm --filter @happyvertical/smrt-commerce test:postgres` is the lane that holds the line (#2361, #2401, #2373).\n- **Rates are the opposite**: `InvoiceLineItem.taxRate` and `ContractLineItem.taxRate` are inherently fractional and must initialize `= 0.0`. INTEGER would truncate every rate to 0. `ContractLineItem.quantity` is decimal for the same reason (contracts price fractional hours/weight/bandwidth); `InvoiceLineItem.quantity` is also decimal (six fractional places); existing integer columns require the explicit [quantity migration](agents/invoice-quantity.md).\n- **Rounding happens where a rate meets money, and nowhere else**: `InvoiceLineItem` uses exact shared invoice arithmetic to round fractional quantity × price and then tax to minor units; `ContractLineItem.calculateAmount()` uses `Math.round()` for tax. Everything downstream is exact integer arithmetic, which is why **there are no `EPSILON` tolerances left on any money path** (#2401). `Invoice`, `PaymentAllocation`, `Payout` and `PaymentIntent` compare with `===` / `>` / `>=`. Do not reintroduce a tolerance: against integers it forgives a real one-cent discrepancy rather than float fuzz. (`FulfillmentLineItem`'s quantity epsilon is unrelated — quantities are genuinely decimal there.)\n- **Migrating an existing database to minor units**: `preflightCommerceMoneyMinorUnits(db)` reports, per column, whether it still holds major units and which rows would be rounded or exceed JavaScript's safe-integer range; `migrateCommerceMoneyToMinorUnits(db)` converts them. Both are exported from the package root. The rescale is idempotent via a `_smrt_backfills` marker, changes the column type in place on PostgreSQL/DuckDB (`ALTER … TYPE BIGINT USING round(col * 100)`), and on SQLite rescales values only — SQLite cannot alter a declared type in place, so those columns come back in `declaredTypeChangePending` and need the table-rebuild path (#2370).\n- **`Payment.nativeAmount` is NOT in that migration, and must not be.** Its minor unit is a property of the *row's asset*: satoshis on a BTC rail (×1e8), cents on a fiat or stablecoin rail (×1e2), in one column discriminated only by `nativeCurrency`. A blanket ×100 turns 0.00713 BTC into `1` instead of `713000` sats, and a round 0.01 BTC even passes the preflight's integrality check while being wrong by six orders of magnitude. Convert it in two deliberate steps — normalise each row to its own asset's minor units while the column is still floating-point, then `rescaleMoneyColumnsToMinorUnits(db, COMMERCE_NATIVE_UNIT_COLUMNS, { scale: 1, … })` for the type change. `COMMERCE_NATIVE_UNIT_COLUMNS` is exported with a worked example; step one is deliberately the deployment's to write, because only it knows which `nativeCurrency` values it has used.\n- **`PaymentIntent.paymentOptions[].nativeAmount` has the same per-asset problem inside a JSON column and is likewise not migrated.** An intent's price lock defaults to 15 minutes, so the supported answer is to let open intents expire and be re-quoted: an unconverted option fails the exact `!==` reconciliation against the payment that arrives, which is a loud failure rather than a silently mis-scaled quote.\n- **Range and existing deployments**: fresh PostgreSQL/DuckDB INTEGER columns are BIGINT, and the runtime rejects values outside JavaScript's safe-integer range rather than rounding them. Existing PostgreSQL `int4` columns do not self-repair; widen them through the explicit migration tracked in #2424.\n- **Journals posted from commerce carry minor units**: `Payment.recordPayment()` and `Invoice.recognizeRevenue()` write `amount` / `totalAmount` straight into smrt-ledgers entries. smrt-ledgers is unit-agnostic (its `BALANCE_EPSILON` only checks debits === credits), and integer entries balance exactly, so this is strictly tighter than the major-unit journals commerce used to post.\n- **Invoice controls payment status**: not the Payment model — use `Invoice.updatePaymentStatus()`\n- **Tax rate is external**: no tax rate field on Invoice — rate must be calculated externally\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; editor-mode recovery and existing-column migration are 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.\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- **`Invoice.providerTaxAmount`** is added to line-item tax; it is\n  server-managed (not API-writable). `toAccountingInput()` 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- **Currency is integer minor units** (cents, satoshis) — `$19.99` is `1999`, like affiliates. Money is exact, so money fields initialize `= 0`, never `= 0.0`: the integer literal is what maps them to INTEGER columns (BIGINT on fresh PostgreSQL/DuckDB databases). Writing a fractional major-unit value is the bug — the model rejects it via `assertIntegerMinorUnits` on `Invoice`/`Payment`/`PaymentAllocation`/`Payout`/`Contract` before the database sees it, because PostgreSQL would reject it with `22P02` while SQLite's affinity silently stores it. `pnpm --filter @happyvertical/smrt-commerce test:postgres` is the lane that holds the line (#2361, #2401, #2373).\n- **Rates are the opposite**: `InvoiceLineItem.taxRate` and `ContractLineItem.taxRate` are inherently fractional and must initialize `= 0.0`. INTEGER would truncate every rate to 0. `ContractLineItem.quantity` is decimal for the same reason (contracts price fractional hours/weight/bandwidth); `InvoiceLineItem.quantity` is also decimal (six fractional places); existing integer columns require the explicit [quantity migration](agents/invoice-quantity.md).\n- **Rounding happens where a rate meets money, and nowhere else**: `InvoiceLineItem` uses exact shared invoice arithmetic to round fractional quantity × price and then tax to minor units; `ContractLineItem.calculateAmount()` uses `Math.round()` for tax. Everything downstream is exact integer arithmetic, which is why **there are no `EPSILON` tolerances left on any money path** (#2401). `Invoice`, `PaymentAllocation`, `Payout` and `PaymentIntent` compare with `===` / `>` / `>=`. Do not reintroduce a tolerance: against integers it forgives a real one-cent discrepancy rather than float fuzz. (`FulfillmentLineItem`'s quantity epsilon is unrelated — quantities are genuinely decimal there.)\n- **Migrating an existing database to minor units**: `preflightCommerceMoneyMinorUnits(db)` reports, per column, whether it still holds major units and which rows would be rounded or exceed JavaScript's safe-integer range; `migrateCommerceMoneyToMinorUnits(db)` converts them. Both are exported from the package root. The rescale is idempotent via a `_smrt_backfills` marker, changes the column type in place on PostgreSQL/DuckDB (`ALTER … TYPE BIGINT USING round(col * 100)`), and on SQLite rescales values only — SQLite cannot alter a declared type in place, so those columns come back in `declaredTypeChangePending` and need the table-rebuild path (#2370).\n- **`Payment.nativeAmount` is NOT in that migration, and must not be.** Its minor unit is a property of the *row's asset*: satoshis on a BTC rail (×1e8), cents on a fiat or stablecoin rail (×1e2), in one column discriminated only by `nativeCurrency`. A blanket ×100 turns 0.00713 BTC into `1` instead of `713000` sats, and a round 0.01 BTC even passes the preflight's integrality check while being wrong by six orders of magnitude. Convert it in two deliberate steps — normalise each row to its own asset's minor units while the column is still floating-point, then `rescaleMoneyColumnsToMinorUnits(db, COMMERCE_NATIVE_UNIT_COLUMNS, { scale: 1, … })` for the type change. `COMMERCE_NATIVE_UNIT_COLUMNS` is exported with a worked example; step one is deliberately the deployment's to write, because only it knows which `nativeCurrency` values it has used.\n- **`PaymentIntent.paymentOptions[].nativeAmount` has the same per-asset problem inside a JSON column and is likewise not migrated.** An intent's price lock defaults to 15 minutes, so the supported answer is to let open intents expire and be re-quoted: an unconverted option fails the exact `!==` reconciliation against the payment that arrives, which is a loud failure rather than a silently mis-scaled quote.\n- **Range and existing deployments**: fresh PostgreSQL/DuckDB INTEGER columns are BIGINT, and the runtime rejects values outside JavaScript's safe-integer range rather than rounding them. Existing PostgreSQL `int4` columns do not self-repair; widen them through the explicit migration tracked in #2424.\n- **Journals posted from commerce carry minor units**: `Payment.recordPayment()` and `Invoice.recognizeRevenue()` write `amount` / `totalAmount` straight into smrt-ledgers entries. smrt-ledgers is unit-agnostic (its `BALANCE_EPSILON` only checks debits === credits), and integer entries balance exactly, so this is strictly tighter than the major-unit journals commerce used to post.\n- **Invoice controls payment status**: not the Payment model — use `Invoice.updatePaymentStatus()`\n- **Tax rate is external**: no tax rate field on Invoice — rate must be calculated externally\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",
   "moduleDocs": [
     {
       "path": "agents/customer-vendor-ui.md",
       "module": "customer-vendor-ui",
       "content": "# Customer and vendor UI\n\nImport the provider-free surfaces from `@happyvertical/smrt-commerce/svelte`:\n\n```svelte\n<script lang=\"ts\">\n  import {\n    CustomerDirectory,\n    CustomerDetail,\n    CustomerForm,\n    VendorDirectory,\n    VendorDetail,\n    VendorForm,\n    type CustomerDisplayData,\n  } from '@happyvertical/smrt-commerce/svelte';\n\n  let { data, form } = $props();\n</script>\n\n<CustomerForm\n  mode=\"edit\"\n  values={form?.values ?? data.values}\n  errors={form?.errors}\n  transport={{\n    action: '?/update',\n    method: 'post',\n    hiddenFields: {\n      requestId: form?.values.requestId ?? data.requestId,\n      expectedTenantId: data.tenantId,\n    },\n  }}\n  labels={{ singular: 'Client', plural: 'Clients' }}\n  cancelHref={`/clients/${data.customer.id}`}\n/>\n```\n\nThe caller owns action URLs, server authorization, tenancy checks, request tokens, persistence, and retry behavior. Capability props only decide whether an affordance is rendered. The components never create a Profile, Customer, Vendor, or contact relationship and never generate request tokens; the server writes posted contact rows with `savePartyContacts()` ([contact rows](#contact-rows-3501)).\n\n`CustomerDisplayData.creditLimitMinor` and `VendorDisplayData.minimumOrderMinor` are integer currency minor units. Detail components convert them only for display and accept an explicit `minorUnitExponent`. Form values deliberately use retained strings such as `1250.00`; the server validates and converts those major-unit strings to the model's integer minor units.\n\n`VendorFormValues.leadTimeDays` is also retained text. The control supplies a numeric keyboard hint without browser number-input sanitization, and the server must parse and validate the submitted non-negative integer.\n\nForms use the provider-free `Form`, `Input`, `Select`, `Textarea`, and `Checkbox` controls from `@happyvertical/smrt-ui/forms`. They default to native `POST` submission through `preventDefault={false}`. `transport.hiddenFields`, `transport.intentName`, and the field-name maps let an application preserve its existing payload contract. Repeatable contact rows submit repeated field names in DOM order. Add and remove controls are native submitters, so they work without JavaScript; the server returns the revised rows and retained values.\n\n`CustomerForm` and `VendorForm` accept submit hooks so a host never has to find\nthe form after mount (#3501). `enhance` (`PartyFormEnhance`, action-shaped) is\napplied to the mounted native `<form>` and destroyed with it; SvelteKit's\n`enhance` from `$app/forms` fits directly, or wrap it to pass a submit callback.\nAn `ssr = false` app needs it, because a plain native post answers with the\nempty shell. `onsubmit` receives the native submit event (submission stays\nnative unless it calls `preventDefault()`), and the `getFormElement()` instance\nmethod returns the native element while mounted.\n\n```svelte\n<script lang=\"ts\">\n  import { enhance } from '$app/forms';\n</script>\n\n<VendorForm values={form?.values ?? data.values} errors={form?.errors} transport={{ action: '?/save' }} {enhance} />\n```\n\nDirectory search forms accept `hiddenFields` as a string record for caller-owned GET state such as sort direction and page size. Fields whose names equal the resolved `queryName` or `statusName` are omitted so the visible search controls remain authoritative.\n\nCustomer shipping and billing addresses use the shared `CountrySelect` and\n`ProvinceSelect`. The native names remain `shippingCountry`, `shippingState`,\n`billingCountry`, and `billingState` unless `fieldNames` overrides them. Changing\ncountry changes the region control without clearing its current string; CA and US\nrender localized subdivision choices, while unsupported countries render an\neditable text field. Unknown values remain selectable/postable after a failed\nsubmission. Use `countryOptions` or `provinceOptions` only when the caller must\nrestrict the choices. `VendorForm` has no structured address fields in its public\nDTO and does not invent them.\n\nVendor currency uses the shared `CurrencySelect`. The raw retained string remains\nthe native `currency` payload, including unknown values returned after validation.\nUse `currencyOptions` for caller-authorized restrictions; omitted options use the\nshared currency catalog. Selector labels follow the active smrt-ui i18n locale.\n\nThe forms place a non-focusable default save submitter before contact row actions so Enter in a text field cannot accidentally add or remove a contact. This remains in place when the `actions` snippet customizes the visible action bar; set `transport.saveIntent` to the custom save intent.\n\nUse the `extension` snippets for application fields such as construction roles and trades. Keep those fields and their policy in the application:\n\n```svelte\n<VendorForm values={data.values} transport={{ action: '?/save' }}>\n  {#snippet extension(values)}\n    <ConstructionVendorFields roles={values.roles} trades={values.trades} />\n  {/snippet}\n</VendorForm>\n```\n\nDirectory entries carry caller-owned detail links and pagination links. Detail edit links and form submit buttons appear only when their capability props allow them; the server must still authorize every request.\n\n`CustomerDirectory`, `CustomerDetail`, `VendorDirectory`, and `VendorDetail`\nrender a `PageHeader` (the page `h1`, a subtitle, and the add/edit action) by\ndefault. A host that frames every page itself passes `headless` to render only\nthe body, then renders its own heading and create/edit affordance; or passes a\n`header` snippet to replace the built-in header in place (#3501). `backHref`\nstays independent of both.\n\nDirectory empty and filter behavior follows this contract:\n\n| State | Empty guidance | Native form behavior |\n| --- | --- | --- |\n| No query, status, or caller filter is active | Explain that no records have been added; when `canCreate` and `addHref` are present, point to creating the first record | Search and status controls retain their normal names |\n| Query or status is active | Suggest changing search or filters | Visible query/status controls remain authoritative over same-named `hiddenFields` |\n| A caller-owned filter is active | Suggest changing search or filters | Render the `filters` snippet inside the directory form and list its names in `filterNames` so same-named hidden fields are omitted |\n| Caller supplies `emptyDescription` | Render the supplied description | Submission behavior is unchanged |\n\nThe `filters` snippet is for domain-adjacent GET controls that belong beside\nsearch and status, such as a trade classification. It does not move filtering\nor authorization into the component. `hasAdditionalFilters` describes whether\nthose controls currently narrow the result, while `filterNames` prevents a\nhidden/visible duplicate name from changing native form serialization.\n\nThe registry keys are `customer-directory`, `customer-detail`, `customer-form`, `vendor-directory`, `vendor-detail`, `vendor-form`, and `party-contact-fields`. Interactive examples are published by `@happyvertical/smrt-commerce/playground` and ship in the next generated Commerce package release. DomaCraft can replace its local routes incrementally by adapting its existing server DTOs and payload names; no identity or database migration is required.\n\nThe form playground previews handle save, add-contact, and remove-contact intents in memory. They deliberately return a simulated validation error on save so retained values and retry behavior can be inspected without a backend.\n\n## Contact rows (#3501)\n\n`Customer.contacts` / `Vendor.contacts` store `PartyContact` rows (JSON\ncolumn; additive schema, run `smrt db:migrate`). The root package exports the\nserver half of the form's contact payload:\n\n| Export | Contract |\n| --- | --- |\n| `readPartyContactRows(form, fieldNames?)` | Zips the repeated `contactId`, `contactName`, `contactLabel`, `contactEmail`, `contactPhone`, `contactAddress` values (or the form's `fieldNames` overrides) in DOM order into raw `PartyContactInput` rows. The editable contact block always posts a hidden `contactCount` marker with its row count; a missing marker (`reason: 'missing'`) or any disagreeing count (`'misaligned'`) throws `PartyContactPayloadError`, so zero rows mean an empty list only when the block rendered. |\n| `applyPartyContactIntent(rows, intent, intents?)` | `addContact` appends a blank row; `removeContact:<n>` (or a caller `parseRemoveIntent`) drops row `n`. `handled: true` means render the returned rows and do not save, including for a stale index. |\n| `validatePartyContactRows(rows)` | Trims, drops blank rows, and returns `errors` aligned with the submitted rows using codes `too_long` (limits in `PARTY_CONTACT_MAX_LENGTHS`, matching the inputs) and `invalid_email`. |\n| `savePartyContacts(collection, partyId, formOrRows, { fieldNames?, expectedTenantId? })` | Given the posted form, reads it with `readPartyContactRows` (marker enforced); an array is taken as rows already read that way. Loads the party with `collection.get()` (so the active tenant context scopes it) and replaces its contacts: posted ids are kept, new rows get a random id, unposted rows are removed. A posted id the party does not have is `unknown_contact` on `id`. Invalid input throws `PartyContactValidationError` (`errors`, nothing written); a missing or other-tenant party throws `PartyContactPartyNotFoundError`. |\n\nError codes are not messages: map `PartyContactValidationError.errors` to\nlocalized strings for `PartyFormErrors.contacts`, and return the submitted\nrows as retained `values.contacts`. A form with custom contact `fieldNames`\nmust pass the same names when reading; with mismatched names the marker is\nnot found and the read fails closed instead of removing every contact. Saves are a read-modify-write of the party\nrow (last writer wins). Map saved contacts to `CustomerDisplayData.contacts` /\n`VendorDisplayData.contacts` for the detail screens.\n\n## Selectors (#3602)\n\n`CustomerSelect` and `VendorSelect` are field-sized pickers built on the shared\nsmrt-ui `RelationInput` (`@happyvertical/smrt-ui/forms`, ARIA 1.2 combobox),\nthrough one internal `PartySelect` adapter that maps party DTOs to relation\noptions and localizes the field's text. Search, resolve, debounce, stale-result\nand create handling live in `RelationInput`, not here.\n\n| Prop | Meaning |\n| --- | --- |\n| `name`, `value` (bindable), `label`, `required`, `disabled`, `error`, `placeholder`, `description` | Field basics. `label` defaults to the localized \"Customer\"/\"Vendor\"; `error` renders a linked `role=\"alert\"`. |\n| `search(query)` | Caller-owned lookup returning party DTOs; called with `''` when the list opens and, debounced (`debounceMs`, default 250), as the person types. |\n| `resolve(id)` | Caller-owned lookup of the current value's DTO when it has not been listed; without it a value stays blank until searched. |\n| `onCreate(query)` | Optional. Renders \"+ New customer/vendor\" (`createLabel` overrides); a returned DTO is selected. |\n| `onchange(id)`, `interaction` | Change callback (`''` when cleared) and agent-interaction options. |\n\nRows show `profile.name` with localized status and, for customers, type\n(`Active · Wholesale`). Data never enters the component: no stores, no fetches,\nno tenant logic. A failed `search` shows an inline status, not an exception;\na failed `onCreate` leaves the field as it was. Text comes from the\n`commerce.select.*` messages. The selectors are registered as the\n`customer-select` and `vendor-select` slots, whose `selects` qualified names\nare emitted into the manifest's `uiSelectors`; keep `selects` a string literal\nso the scanner can read it.\n\nWidget hints (`@field({ ui: { widget } })`, #3599) are presentation-only and\nthe build rejects them on non-text fields; `currency` is a currency-code\npicker for ISO 4217 strings and is never applied to minor-unit amounts;\namounts take `ui: { format: 'money' }` instead (#3718).\nBehaviour tests run under jsdom: `pnpm exec vitest run --config\nvitest.selects.config.ts` (also part of `pnpm test:ui`).\n\n## Record page hints (#3718)\n\nMinor-unit amounts on Contract, Invoice, their line items, Payment,\nPaymentAllocation, `Customer.creditLimit` and `Vendor.minimumOrderAmount`\ncarry `ui: { format: 'money' }` (#3718; `widget: 'currency'` stays the\ncurrency-code picker on the text `currency` field). Payout and Payment's\nnative/USD drift amounts are not hinted: their currency is a payout rail or\nfixed USD, not the record's `currency`. The line-item FKs\n(`ContractLineItem.contractId`, `InvoiceLineItem.invoiceId`,\n`FulfillmentLineItem.fulfillmentId`) carry `role: 'items'`, so record pages\nrender them as a line-items table with a totals block;\n`src/__tests__/money-hints-manifest.test.ts` pins both.\n"
     },
+    {
+      "path": "README.md",
+      "module": "README",
+      "content": "# @happyvertical/smrt-commerce\n\nCommerce models for the s-m-r-t framework. Covers customers, vendors, contracts (9 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 {\n  Customer, CustomerCollection,\n  Order, ContractCollection,\n  Invoice, InvoiceCollection,\n  Payment, PaymentCollection,\n  ContractStatus, InvoiceStatus, PaymentMethod\n} from '@happyvertical/smrt-commerce';\n\n// Create a customer linked to a profile\nconst customers = await CustomerCollection.create({ db });\nconst customer = await customers.create({\n  profileId: 'profile-uuid',\n  creditLimit: 1000000, // $10,000.00 — money is integer minor units\n  paymentTerms: 'Net 30',\n});\nawait customer.save();\n\n// Create an order (STI contract type)\nconst contracts = await ContractCollection.create({ db });\nconst order = await contracts.create({\n  _meta_type: 'Order',\n  customerId: customer.id,\n  subtotal: 100000, // $1,000.00\n  taxAmount: 5000, // $50.00\n  totalAmount: 105000, // $1,050.00\n  currency: 'CAD',\n});\nawait order.save();\n\n// Create an invoice for the order\nconst invoices = await InvoiceCollection.create({ db });\nconst invoiceNumber = await invoices.generateInvoiceNumber();\nconst invoice = await invoices.create({\n  customerId: customer.id,\n  contractId: order.id,\n  invoiceNumber,\n  subtotal: 100000, // $1,000.00\n  taxAmount: 5000, // $50.00\n  totalAmount: 105000, // $1,050.00\n});\nawait invoice.save();\n\n// Recognize revenue (creates balanced journal in smrt-ledgers)\nawait invoice.recognizeRevenue({\n  arAccountId: 'ar-account-id',\n  revenueAccountId: 'revenue-account-id',\n  taxAccountId: 'tax-account-id',\n});\n\n// Record a payment\nconst payments = await PaymentCollection.create({ db });\nconst payment = await payments.create({\n  contractId: order.id,\n  customerId: customer.id,\n  amount: 105000,\n  method: PaymentMethod.CREDIT_CARD,\n});\nawait payment.save();\n\n// Record payment with ledger integration\nawait payment.recordPayment({\n  ledgerId: 'ledger-id',\n  receivablesAccountId: 'ar-account-id',\n  cashAccountId: 'bank-account-id',\n});\n```\n\n## API\n\n### Models\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 nine 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` requires 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| `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`, `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    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`.\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`InvoiceLineEditor` and `InvoiceEditor` from `@happyvertical/smrt-commerce/svelte`\nprovide editable descriptions/SKUs, fractional quantities, unit prices, flat or\npercentage discounts, explicit or inherited tax, customer, dates, currency and\nterms. Calculated previews use the same exact minor-unit arithmetic exported\nfor server handlers from `@happyvertical/smrt-commerce/invoices`.\n`InvoiceAllocationFields` and `InvoiceReview` extend this foundation with\ncaller-owned sources and approvals. See [the editor contract](agents/invoice-preparation.md),\n[calculation rules](agents/invoice-calculations.md), and the required\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"
+    },
     {
       "path": "agents/invoice-quantity.md",
       "module": "invoice-quantity",
@@ -19900,12 +20490,12 @@
     {
       "path": "agents/quote-ui.md",
       "module": "quote-ui",
-      "content": "# Quotation and estimate presentation\n\nImport `QuoteEditor`, `QuoteRevisionHistory`, `QuoteRevisionComparison` and their\nProps/DTOs from `@happyvertical/smrt-commerce/svelte`. Registry slots are\n`quote-editor`, `quote-revision-history`, and `quote-revision-comparison`.\nCommerce playground has interactive vendor quotation and customer estimate demos.\n\n`kind: 'vendor-quotation'` means received supplier evidence;\n`kind: 'customer-estimate'` means pricing proposed to a customer. Neither widget\nselects pricing, accepts budgets, awards work, sends messages or mutates a model.\nAdapt public Commerce Estimate/Contract fields (`currency`, `totalAmount`,\n`status`, `customerId`/`vendorId`) to these presentation DTOs;\nconstruction package allocation and approval policy remain caller extensions.\nClient records need not become Commerce Customers.\n\n`QuoteRevision.total.amountMinor` is a safe integer or null (unknown), with an\nexplicit `minorUnitDigits` from the owning currency/asset contract. No locale\ninference, monetary rounding or unknown-as-zero comparison occurs. Different\nkinds/currencies/scales cannot produce a delta. Existing invoice `LineItem`\nmajor-unit props retain their established contract. Form money values are raw\n**major-unit strings**: the caller validates and converts before saving; invalid\nstrings remain visible after failed actions. Dates likewise remain text to avoid\nnative date inputs silently clearing rejected server values.\n\nSupply `values`, authorized `counterparties`, `action`, optional `method`,\n`hiddenFields` (name/value pairs), `errors` and `message`. `names` maps payload\nnames to an existing endpoint. `labels.counterparty = 'Client'` supports local\nterminology. `extensions` composes pricing-source/allocation fields;\n`attachments` composes private Assets controls without loading bytes here.\n`QuoteRevisionHistory.evidence(revision)` composes authorized document links.\nAll fixed component text uses the shared i18n catalog; data/status/date labels\ncome from the caller.\n\nCurrency uses the shared `CurrencySelect`, localized by the active smrt-ui i18n\ncontext. Its native name still comes from `names.currency`, and rejected or\nunknown raw strings remain selected for a corrected submission. Pass\n`currencyOptions` only when the caller must restrict the catalog.\n\nRows submit repeated `lineId`, `lineDescription`, `lineQuantity`, `lineUnitRate`.\nDefault submitter `intent` is `save`, `addLine`, or `removeLine:<stable-id>`;\noverride via `intents`. Add/remove are ordinary `formnovalidate` POSTs, including\nall current strings and hidden tokens even without JavaScript. The action must\nread all repeated fields, preserve row IDs, and re-render them; add/remove are\nform-edit operations, not financial writes. Never treat an add-row POST as a save.\n\nThe editor does not generate or rotate submission tokens. Caller-owned\n`@happyvertical/smrt-ui/form-retry` can be attached via `formAttributes` using\nSvelte's `createAttachmentKey()` and `retry.attach`; caller transport enhancement\nmay use `onsubmit`. Use the same server-owned hidden identity when retrying an\nuncertain commit. Never blindly reset after a response. The caller must preserve\nhidden tenant/request/predecessor values, validate authorization on every action,\nand enforce idempotency transactionally. See `docs/content/form-retry.md`.\n`readonly`/`busy` only disable the presented fields; these props are not security.\n\nValidation: `pnpm --filter @happyvertical/smrt-commerce exec vitest run --config vitest.quotes.config.ts`,\n`node packages/commerce/test-support/quote-browser.mjs`, package typecheck/build.\nThe browser harness executes actual SSR POST recovery with JavaScript disabled\nand hydrated demo interactions at 390px. Full release CI/E2E runs at #3423's\nconsolidated release boundary by explicit owner instruction.\n\nOn NixOS, the browser lane accepts the repository-standard\n`PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/run/current-system/sw/bin/chromium`.\nSet `QUOTE_EVIDENCE_DIR` and `CI_TEST_TMPDIR` to an owned evidence directory outside\n`/tmp`. Other commercial tests may reuse its host via\n`QUOTE_BROWSER_EXTENSION=/absolute/fixture.mjs`: export `handleRequest(req, res,\n{vite, render, css, requests})` returning true when handled, and\n`run({browser, baseUrl, evidence, requests})` for additional assertions.\n\nInvalid or unsafe display amounts/scales render localized unavailable text.\nStrict money helpers continue to reject malformed data; presentation recovery\ndoes not validate or authorize submitted money.\n\nThe `attachments` snippet renders outside the editor form so an Assets\n`AttachmentPanel`/`AttachmentUpload` keeps its own multipart action and request\nidentity. The attachment region remains disabled while the editor is read-only\nor busy. Use `extensions` only for controls belonging to the editor submission;\nnever place another form there.\n\nComposition regression: run the quote SSR lane, then the maintained quote browser\nhost with `QUOTE_BROWSER_EXTENSION=packages/commerce/test-support/quote-attachments-browser.mjs`.\nIt submits actual Assets upload bytes and the separate editor action with and\nwithout JavaScript at 390px.\n"
+      "content": "# Quotation and estimate presentation\n\nImport `QuoteEditor`, `QuoteRevisionHistory`, `QuoteRevisionComparison` and their\nProps/DTOs from `@happyvertical/smrt-commerce/svelte`. Registry slots are\n`quote-editor`, `quote-revision-history`, and `quote-revision-comparison`.\nCommerce playground has interactive vendor quotation and customer estimate demos.\n\n`kind: 'vendor-quotation'` means received supplier evidence;\n`kind: 'customer-estimate'` means pricing proposed to a customer. Neither widget\nselects pricing, accepts budgets, awards work, sends messages or mutates a model.\nAdapt Commerce `Estimate` fields (`currency`, `totalAmount`, `status`,\n`customerId`) to customer-estimate DTOs. A received vendor quotation is\ncaller-held evidence or a draft `PurchaseOrder`, not an `Estimate.vendorId`;\nconstruction package allocation and approval policy remain caller extensions.\nClient records need not become Commerce Customers.\n\n`QuoteRevision.total.amountMinor` is a safe integer or null (unknown), with an\nexplicit `minorUnitDigits` from the owning currency/asset contract. No locale\ninference, monetary rounding or unknown-as-zero comparison occurs. Different\nkinds/currencies/scales cannot produce a delta. Existing invoice `LineItem`\nmajor-unit props retain their established contract. Form money values are raw\n**major-unit strings**: the caller validates and converts before saving; invalid\nstrings remain visible after failed actions. Dates likewise remain text to avoid\nnative date inputs silently clearing rejected server values.\n\nSupply `values`, authorized `counterparties`, `action`, optional `method`,\n`hiddenFields` (name/value pairs), `errors` and `message`. `names` maps payload\nnames to an existing endpoint. `labels.counterparty = 'Client'` supports local\nterminology. `extensions` composes pricing-source/allocation fields;\n`attachments` composes private Assets controls without loading bytes here.\n`QuoteRevisionHistory.evidence(revision)` composes authorized document links.\nAll fixed component text uses the shared i18n catalog; data/status/date labels\ncome from the caller.\n\nCurrency uses the shared `CurrencySelect`, localized by the active smrt-ui i18n\ncontext. Its native name still comes from `names.currency`, and rejected or\nunknown raw strings remain selected for a corrected submission. Pass\n`currencyOptions` only when the caller must restrict the catalog.\n\nRows submit repeated `lineId`, `lineDescription`, `lineQuantity`, `lineUnitRate`.\nDefault submitter `intent` is `save`, `addLine`, or `removeLine:<stable-id>`;\noverride via `intents`. Add/remove are ordinary `formnovalidate` POSTs, including\nall current strings and hidden tokens even without JavaScript. The action must\nread all repeated fields, preserve row IDs, and re-render them; add/remove are\nform-edit operations, not financial writes. Never treat an add-row POST as a save.\n\nThe editor does not generate or rotate submission tokens. Caller-owned\n`@happyvertical/smrt-ui/form-retry` can be attached via `formAttributes` using\nSvelte's `createAttachmentKey()` and `retry.attach`; caller transport enhancement\nmay use `onsubmit`. Use the same server-owned hidden identity when retrying an\nuncertain commit. Never blindly reset after a response. The caller must preserve\nhidden tenant/request/predecessor values, validate authorization on every action,\nand enforce idempotency transactionally. See `docs/content/form-retry.md`.\n`readonly`/`busy` only disable the presented fields; these props are not security.\n\nValidation: `pnpm --filter @happyvertical/smrt-commerce exec vitest run --config vitest.quotes.config.ts`,\n`node packages/commerce/test-support/quote-browser.mjs`, package typecheck/build.\nThe browser harness executes actual SSR POST recovery with JavaScript disabled\nand hydrated demo interactions at 390px. Full release CI/E2E runs at #3423's\nconsolidated release boundary by explicit owner instruction.\n\nOn NixOS, the browser lane accepts the repository-standard\n`PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/run/current-system/sw/bin/chromium`.\nSet `QUOTE_EVIDENCE_DIR` and `CI_TEST_TMPDIR` to an owned evidence directory outside\n`/tmp`. Other commercial tests may reuse its host via\n`QUOTE_BROWSER_EXTENSION=/absolute/fixture.mjs`: export `handleRequest(req, res,\n{vite, render, css, requests})` returning true when handled, and\n`run({browser, baseUrl, evidence, requests})` for additional assertions.\n\nInvalid or unsafe display amounts/scales render localized unavailable text.\nStrict money helpers continue to reject malformed data; presentation recovery\ndoes not validate or authorize submitted money.\n\nThe `attachments` snippet renders outside the editor form so an Assets\n`AttachmentPanel`/`AttachmentUpload` keeps its own multipart action and request\nidentity. The attachment region remains disabled while the editor is read-only\nor busy. Use `extensions` only for controls belonging to the editor submission;\nnever place another form there.\n\nComposition regression: run the quote SSR lane, then the maintained quote browser\nhost with `QUOTE_BROWSER_EXTENSION=packages/commerce/test-support/quote-attachments-browser.mjs`.\nIt submits actual Assets upload bytes and the separate editor action with and\nwithout JavaScript at 390px.\n"
     },
     {
       "path": "agents/purchasing-ui.md",
       "module": "purchasing-ui",
-      "content": "# Purchasing and award presentation\n\nPublic `@happyvertical/smrt-commerce/svelte` exports `PurchaseSourceSelector`,\n`PurchaseOrderEditor`, their Props and `Purchase*` DTOs. Registry slots are\n`purchase-source-selector` and `purchase-order-editor`. Interactive playground\nentries cover ordinary amendment and explicit retained-allocation reduction.\n\nThese components use public Commerce PurchaseOrder/Contract as their owning\nfinancial domain without adding a backend command, ledger or fixed approval\npolicy. The caller decides instrument options, source availability, allocation\nlabels, prior commitments, reviewed actuals, floors/ceilings and exact source\nidentity. Construction work packages, accepted budgets, contractor entitlement\nand vendor award policy stay in the consumer. Capability/disabled props only\ncontrol presentation. Every POST needs authoritative server authorization.\n\n`PurchaseSourceSelector` uses a native GET to the supplied action with `name`\n(default `source`) and optional hidden search/context fields. It never writes an\naward. Disabled sources remain visible with caller notices; unknown saved IDs\nremain visible as unavailable. Keep source selection outside a reduction form;\nthe server must reject a downward amendment under an ordinary amendment mode\nand enforce the retained source/instrument during reductions.\n\n`PurchaseOrderEditor` receives `operation` (`create`, `amend`, `reduce`), a\nretained `source`, `currency`, explicit `minorUnitDigits`, raw `values`,\n`instruments`, native POST `action`, and caller-owned `hiddenFields`. Supply\nsource ID, currency, predecessor, tenant and retry IDs in those hidden fields\nunder the exact names your endpoint expects. `names` adapts all built-in fields.\n`labels` adapts approval language; `extensions` and `attachments` compose domain\nfields and authorized Assets evidence without fetching bytes in this component.\n`formAttributes` supports native encoding/ID and caller-owned form-retry Svelte\nattachments; `onsubmit` supports caller transport enhancement. Tokens are never\nminted or rotated here. See the shared [form/action contract](commercial-ui.md)\nand repository `docs/content/form-retry.md`.\n\nAll editable money is **raw major-unit text**, including malformed values and\nempty unknown amounts. The caller parses against the exact currency contract;\nthere is no UI floating-point calculation or implicit blank-to-zero conversion.\nSaved/source/review numbers are safe integer minor units formatted by the\nshared quotation helper. `sourceMinor: null` renders Unknown. Displayed bounds\nare guidance; the server validates floors, ceilings and source eligibility.\n\nEvery allocation posts its stable `id` and amount, even when zero. Mark every\npredecessor allocation `retained: true`. A `reduce` form requires those amounts\nexplicitly and never offers their removal. Supplying fewer predecessor rows is\nnot safe: the server must compare the complete ID set and reject omissions.\nOptional `rowActions` uses native formnovalidate add/remove POSTs carrying all\ncurrent fields; the caller re-renders unchanged rejected strings and IDs.\nNew-row IDs belong to the caller. Row editing never records a commitment.\n\nPressing Enter in an input activates review or record, preserving draft rows.\nExplicit add/remove actions remain available without JavaScript.\nDefault submitter `intent` values are `review`, `record`, `edit`, all configurable.\nOnly a caller-produced `review` snapshot or a retained `retryFingerprint` exposes\nexplicit confirmation. `review.fingerprint` posts under `reviewFingerprint` by\ndefault. After an uncertain outcome, re-render the exact submitted values,\nrequest identity and fingerprint; never fabricate a new intent/token. Confirmation\nis an unchecked required checkbox on native renders and when a new review\nfingerprint arrives in a hydrated form. Its value defaults to\n`yes`. The server must bind fingerprint to all submitted values and authority,\nreject changed/stale review data, and replay identical committed retries.\nRendering a review snapshot or selecting a source never accepts/records anything.\n\nValidation: `pnpm --filter @happyvertical/smrt-commerce exec vitest run --config\nvitest.purchasing.config.ts`, owning build/typecheck/pack checks, and the shared\nquote native/hydrated browser harness with `QUOTE_BROWSER_EXTENSION` pointing at\n`packages/commerce/test-support/purchasing-browser-extension.mjs`. Full repository\nCI/E2E is consolidated at the #3423 release boundary by owner instruction.\n\nInvalid or unsafe display amounts/scales render localized unavailable text.\nStrict money helpers continue to reject malformed data; presentation recovery\ndoes not validate or authorize submitted money.\n\nThe `attachments` snippet renders outside the editor form so an Assets\n`AttachmentPanel`/`AttachmentUpload` keeps its own multipart action and request\nidentity. The attachment region remains disabled while the editor is read-only\nor busy. Use `extensions` only for controls belonging to the editor submission;\nnever place another form there.\n\nComposition regression: run the quote SSR lane, then the maintained quote browser\nhost with `QUOTE_BROWSER_EXTENSION=packages/commerce/test-support/quote-attachments-browser.mjs`.\nIt submits actual Assets upload bytes and the separate editor action with and\nwithout JavaScript at 390px.\n\n## Purchase-order header\n\n`PurchaseOrderHeaderForm` (`purchase-order-header-form` registry slot) edits only\n`vendorId`, `reference`, `notes`, `expectedDate` and `shipTo`. It does not amend\nawards, allocations, totals or status. Supply `action`, caller-authorized `vendors`,\nraw `values`, canonical-key `errors`, optional `message`, `hiddenFields` and\n`names` for an existing endpoint. The native POST submitter defaults to\n`intent=saveHeader`; `intent`, `onsubmit` and `formAttributes` adapt transport.\nReadonly/busy are presentation controls, never authorization. The server must\ncheck active authority, vendor eligibility and any order-status edit policy.\n\nAll header input remains text: even rejected calendar dates survive a rerender.\nThe server validates `expectedDate` as YYYY-MM-DD or empty before saving. An\nunknown retained vendor appears explicitly unavailable but retains its ID on POST\nso a rejected submission cannot silently clear it. The caller must reject an\nunavailable vendor or explicitly permit keeping the existing relationship.\n`shipTo` is a delivery address/instructions snapshot, not a Profile reference.\n`PurchaseOrder.expectedDate` and `.shipTo` use existing STI metadata, default to\nempty strings, and accept `PurchaseOrderOptions`; no table migration is needed.\nExisting Contract fields own the other three values. Header persistence uses the\nexisting SQLite/PostgreSQL Contract schema; DuckDB rejects its existing\nON UPDATE CASCADE foreign keys and is not a supported Contract storage lane. Caller retry identities\nare rendered unchanged; the form itself never persists or retries a mutation.\n\nHeader regression evidence uses the purchasing SSR suite and the shared quote\nbrowser host with `QUOTE_BROWSER_EXTENSION=packages/commerce/test-support/purchasing-header-browser.mjs`.\n"
+      "content": "# Purchasing and award presentation\n\nPublic `@happyvertical/smrt-commerce/svelte` exports `PurchaseSourceSelector`,\n`PurchaseOrderEditor`, their Props and `Purchase*` DTOs. Registry slots are\n`purchase-source-selector` and `purchase-order-editor`. Interactive playground\nentries cover ordinary amendment and explicit retained-allocation reduction.\n\nThese components use public Commerce PurchaseOrder/Contract as their owning\nfinancial domain without adding a backend command, ledger or fixed approval\npolicy. The caller decides instrument options, source availability, allocation\nlabels, prior commitments, reviewed actuals, floors/ceilings and exact source\nidentity. Construction work packages, accepted budgets, contractor entitlement\nand vendor award policy stay in the consumer. Capability/disabled props only\ncontrol presentation. Every POST needs authoritative server authorization.\n\n`PurchaseSourceSelector` uses a native GET to the supplied action with `name`\n(default `source`) and optional hidden search/context fields. It never writes an\naward. Disabled sources remain visible with caller notices; unknown saved IDs\nremain visible as unavailable. Keep source selection outside a reduction form;\nthe server must reject a downward amendment under an ordinary amendment mode\nand enforce the retained source/instrument during reductions.\n\n`PurchaseOrderEditor` receives `operation` (`create`, `amend`, `reduce`), a\nretained `source`, `currency`, explicit `minorUnitDigits`, raw `values`,\n`instruments`, native POST `action`, and caller-owned `hiddenFields`. Supply\nsource ID, currency, predecessor, tenant and retry IDs in those hidden fields\nunder the exact names your endpoint expects. `names` adapts all built-in fields.\n`labels` adapts approval language; `extensions` and `attachments` compose domain\nfields and authorized Assets evidence without fetching bytes in this component.\n`formAttributes` supports native encoding/ID and caller-owned form-retry Svelte\nattachments; `onsubmit` supports caller transport enhancement. Tokens are never\nminted or rotated here. See the shared [form/action contract](commercial-ui.md)\nand repository `docs/content/form-retry.md`.\n\nAll editable money is **raw major-unit text**, including malformed values and\nempty unknown amounts. The caller parses against the exact currency contract;\nthere is no UI floating-point calculation or implicit blank-to-zero conversion.\nSaved/source/review numbers are safe integer minor units formatted by the\nshared quotation helper. `sourceMinor: null` renders Unknown. Displayed bounds\nare guidance; the server validates floors, ceilings and source eligibility.\n\nEvery allocation posts its stable `id` and amount, even when zero. Mark every\npredecessor allocation `retained: true`. A `reduce` form requires those amounts\nexplicitly and never offers their removal. Supplying fewer predecessor rows is\nnot safe: the server must compare the complete ID set and reject omissions.\nOptional `rowActions` uses native formnovalidate add/remove POSTs carrying all\ncurrent fields; the caller re-renders unchanged rejected strings and IDs.\nNew-row IDs belong to the caller. Row editing never records a commitment.\n\nPressing Enter in an input activates review or record, preserving draft rows.\nExplicit add/remove actions remain available without JavaScript.\nDefault submitter `intent` values are `review`, `record`, `edit`, all configurable.\nOnly a caller-produced `review` snapshot or a retained `retryFingerprint` exposes\nexplicit confirmation. `review.fingerprint` posts under `reviewFingerprint` by\ndefault. After an uncertain outcome, re-render the exact submitted values,\nrequest identity and fingerprint; never fabricate a new intent/token. Confirmation\nis an unchecked required checkbox on native renders and when a new review\nfingerprint arrives in a hydrated form. Its value defaults to\n`yes`. The server must bind fingerprint to all submitted values and authority,\nreject changed/stale review data, and replay identical committed retries.\nRendering a review snapshot or selecting a source never accepts/records anything.\n\nValidation: `pnpm --filter @happyvertical/smrt-commerce exec vitest run --config\nvitest.purchasing.config.ts`, owning build/typecheck/pack checks, and the shared\nquote native/hydrated browser harness with `QUOTE_BROWSER_EXTENSION` pointing at\n`packages/commerce/test-support/purchasing-browser-extension.mjs`. Full repository\nCI/E2E is consolidated at the #3423 release boundary by owner instruction.\n\nInvalid or unsafe display amounts/scales render localized unavailable text.\nStrict money helpers continue to reject malformed data; presentation recovery\ndoes not validate or authorize submitted money.\n\nThe `attachments` snippet renders outside the editor form so an Assets\n`AttachmentPanel`/`AttachmentUpload` keeps its own multipart action and request\nidentity. The attachment region remains disabled while the editor is read-only\nor busy. Use `extensions` only for controls belonging to the editor submission;\nnever place another form there.\n\nComposition regression: run the quote SSR lane, then the maintained quote browser\nhost with `QUOTE_BROWSER_EXTENSION=packages/commerce/test-support/quote-attachments-browser.mjs`.\nIt submits actual Assets upload bytes and the separate editor action with and\nwithout JavaScript at 390px.\n\n## Purchase-order header\n\n`PurchaseOrderHeaderForm` (`purchase-order-header-form` registry slot) edits only\n`vendorId`, `reference`, `notes`, `expectedDate` and `shipTo`. It does not amend\nawards, allocations, totals or status. Supply `action`, caller-authorized `vendors`,\nraw `values`, canonical-key `errors`, optional `message`, `hiddenFields` and\n`names` for an existing endpoint. The native POST submitter defaults to\n`intent=saveHeader`; `intent`, `onsubmit` and `formAttributes` adapt transport.\nReadonly/busy are presentation controls, never authorization. The server must\ncheck active authority, vendor eligibility and any order-status edit policy.\n\nAll header input remains text: even rejected calendar dates survive a rerender.\nThe server validates `expectedDate` as YYYY-MM-DD or empty before saving. An\nunknown retained vendor appears explicitly unavailable but retains its ID on POST\nso a rejected submission cannot silently clear it. The caller must reject an\nunavailable vendor or explicitly permit keeping the existing relationship.\n`shipTo` is a delivery address/instructions snapshot, not a Profile reference.\n`PurchaseOrder.expectedDate` and `.shipTo` use existing STI metadata, default to\nempty strings, and accept `PurchaseOrderOptions`; no table migration is needed.\n`PurchaseContract` owns `vendorId`; `Contract` owns `reference` and `notes`.\nHeader persistence uses the existing SQLite/PostgreSQL Contract schema. DuckDB\nrejects its existing ON UPDATE CASCADE foreign keys and is not a supported\nContract storage lane. Caller retry identities\nare rendered unchanged; the form itself never persists or retries a mutation.\n\nHeader regression evidence uses the purchasing SSR suite and the shared quote\nbrowser host with `QUOTE_BROWSER_EXTENSION=packages/commerce/test-support/purchasing-header-browser.mjs`.\n"
     },
     {
       "path": "agents/cost-billing.md",
@@ -19967,11 +20557,7 @@
             },
             "customerId": {
               "label": "Customer",
-              "order": 1,
-              "required": true
-            },
-            "vendorId": {
-              "visibility": "hidden"
+              "order": 1
             },
             "subtotal": {
               "visibility": "hidden"
@@ -20132,14 +20718,9 @@
               "visibility": "hidden",
               "locked": true
             },
-            "vendorId": {
-              "visibility": "hidden",
-              "locked": true
-            },
             "customerId": {
               "label": "Customer",
-              "order": 1,
-              "required": true
+              "order": 1
             },
             "channelId": {
               "visibility": "hidden"
@@ -20504,11 +21085,7 @@
             },
             "customerId": {
               "label": "Customer",
-              "order": 1,
-              "required": true
-            },
-            "vendorId": {
-              "visibility": "hidden"
+              "order": 1
             },
             "subtotal": {
               "visibility": "hidden"
@@ -20609,11 +21186,7 @@
             },
             "customerId": {
               "label": "Customer",
-              "order": 1,
-              "required": true
-            },
-            "vendorId": {
-              "visibility": "hidden"
+              "order": 1
             },
             "subtotal": {
               "visibility": "hidden"
@@ -20707,10 +21280,6 @@
               "visibility": "hidden",
               "locked": true
             },
-            "customerId": {
-              "visibility": "hidden",
-              "locked": true
-            },
             "vendorId": {
               "label": "Vendor",
               "order": 1
@@ -20813,14 +21382,9 @@
               "visibility": "hidden",
               "locked": true
             },
-            "vendorId": {
-              "visibility": "hidden",
-              "locked": true
-            },
             "customerId": {
               "label": "Customer",
-              "order": 1,
-              "required": true
+              "order": 1
             },
             "channelId": {
               "visibility": "hidden"
@@ -20975,10 +21539,6 @@
               "visibility": "hidden",
               "locked": true
             },
-            "vendorId": {
-              "visibility": "hidden",
-              "locked": true
-            },
             "customerId": {
               "label": "Customer",
               "order": 1