@happyvertical/smrt-commerce 0.40.70 → 0.41.0

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-commerce",
-  "packageVersion": "0.40.70",
+  "packageVersion": "0.41.0",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "b4ba0fc63508ddd792a0c8fea7cf69931385ea71be22cab0833449244813acd8",
-    "packageJson": "d29fa5f546970d0f3fc632627fa51b3ea7cdc07a2b7f8386657c50d0a3dae5c2",
-    "agents": "4cb60c848cfe4e23ba75d5b0008ecf8ea83cd5de2d29d8aa5d8c329bda7523f7"
+    "manifest": "46c5eaaae97f2c1daa76b6ca5997adfdfe97e4380af9b2af84c9b7178338a325",
+    "packageJson": "641681852d15c8d85afaa5ecae3690ce81b2f33c0596ab4d0a97b5a4bd1689f6",
+    "agents": "0779ea7ef940bbdd32682920ad6ce6e95e402337a9e22c7db24361f5c302527d"
   },
   "exports": [
     ".",
@@ -1434,23 +1434,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -1869,6 +1869,12 @@
         "field": "tenantId"
       },
       "tableStrategy": "sti",
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context",
+        "_meta_type"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -2006,23 +2012,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -2503,23 +2509,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -3000,23 +3006,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -3497,23 +3503,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -3994,23 +4000,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -4491,23 +4497,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -4988,23 +4994,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -5497,23 +5503,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -5994,23 +6000,23 @@
         },
         {
           "name": "subtotal",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "taxAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "totalAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -6586,16 +6592,16 @@
         },
         {
           "name": "unitPrice",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "discount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -6607,9 +6613,9 @@
         },
         {
           "name": "amount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -6999,6 +7005,12 @@
         "field": "tenantId"
       },
       "tableStrategy": "sti",
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context",
+        "_meta_type"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -7114,9 +7126,9 @@
         },
         {
           "name": "creditLimit",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -7206,6 +7218,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -7432,6 +7449,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -7589,6 +7611,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -7999,6 +8026,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -8141,9 +8173,9 @@
         },
         {
           "name": "taxRate",
-          "type": "integer",
+          "type": "decimal",
           "required": false,
-          "columnType": "INTEGER",
+          "columnType": "REAL",
           "default": 0
         },
         {
@@ -8249,6 +8281,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -8371,9 +8408,9 @@
         },
         {
           "name": "amount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -8465,9 +8502,9 @@
         },
         {
           "name": "nativeAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -8479,16 +8516,16 @@
         },
         {
           "name": "usdAtQuote",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "usdAtConfirmation",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         }
       ],
@@ -8584,6 +8621,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -8755,6 +8797,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -8938,6 +8985,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -9072,9 +9124,9 @@
         },
         {
           "name": "usdPriceLocked",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -9393,23 +9445,23 @@
         },
         {
           "name": "grossAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "operatorFee",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
           "name": "supplierNet",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -9553,6 +9605,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -9632,9 +9689,9 @@
         },
         {
           "name": "minimumOrderAmount",
-          "type": "decimal",
+          "type": "integer",
           "required": false,
-          "columnType": "REAL",
+          "columnType": "INTEGER",
           "default": 0
         },
         {
@@ -9752,6 +9809,11 @@
         "mode": "optional",
         "field": "tenantId"
       },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -10765,5 +10827,5 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 97
   },
-  "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). 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**: line items on invoices.\n- **Payment** / **PaymentAllocation**: tracks payments against invoices. Status controlled by `Invoice.updatePaymentStatus()`, not Payment model. 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. Use `PaymentInstrumentCollection.setDefaultForCustomer()` to change the default so the single-default-per-customer invariant is enforced; generated create/update routes cannot write `isDefault` directly.\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 via natural key `(tenant_id, offering_ref, licensee_email, idempotency_key)` and `PaymentIntentCollection.getOrCreateByIdempotencyKey()`.\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` (1¢ rounding tolerance) enforced on save. `PayoutCollection.createFromPayment()` is the typical entry point; it pulls native amount / currency from the source Payment.\n- **Fulfillment** / **FulfillmentLineItem**: shipment/delivery tracking.\n\n## Ledger Integration\n\n`@happyvertical/smrt-ledgers` is a regular dependency, loaded lazily via dynamic `import()` so the coupling stays runtime-only (no hard static import; the package graph stays a DAG — see #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## 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\n## Gotchas\n\n- **Optional tenancy**: all models `@TenantScoped({ mode: 'optional' })` + nullable tenantId\n- **Currency in decimal fields**: price, taxAmount, totalAmount (not integer cents like affiliates)\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 `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- **PaymentInstrument defaults**: `isDefault` is domain-managed, not API-writable. Call `setDefaultForCustomer(customerId, instrumentId)` so the target is validated and the customer's other instruments are cleared.\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"
+  "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). 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**: line items on invoices.\n- **Payment** / **PaymentAllocation**: tracks payments against invoices. Status controlled by `Invoice.updatePaymentStatus()`, not Payment model. 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. Use `PaymentInstrumentCollection.setDefaultForCustomer()` to change the default so the single-default-per-customer invariant is enforced; generated create/update routes cannot write `isDefault` directly.\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 via natural key `(tenant_id, offering_ref, licensee_email, idempotency_key)` and `PaymentIntentCollection.getOrCreateByIdempotencyKey()`.\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## Ledger Integration\n\n`@happyvertical/smrt-ledgers` is a regular dependency, loaded lazily via dynamic `import()` so the coupling stays runtime-only (no hard static import; the package graph stays a DAG — see #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## 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\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. 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).\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 an integer count.\n- **Rounding happens where a rate meets money, and nowhere else**: `InvoiceLineItem.getTaxAmount()` and `ContractLineItem.calculateAmount()` `Math.round()` the fractional product to whole minor units. 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 overflow `int4`; `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 INTEGER 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- **`int4` ceiling**: INTEGER is 32-bit on PostgreSQL, so every money column tops out near 2.1e9 minor units — about $21.4M, or ~21 BTC in satoshis on `Payment.nativeAmount`. The preflight lists rows that would overflow. Widening to BIGINT is parked in #2373 and is a plain widening whenever it lands.\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 `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- **PaymentInstrument defaults**: `isDefault` is domain-managed, not API-writable. Call `setDefaultForCustomer(customerId, instrumentId)` so the target is validated and the customer's other instruments are cleared.\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"
 }