@happyvertical/smrt-commerce 0.31.0 → 0.32.0

package/dist/manifest.json

@@ -1,8 +1,8 @@
 {
   "version": "1.0.0",
-  "timestamp": 1782183792503,
+  "timestamp": 1782198546055,
   "packageName": "@happyvertical/smrt-commerce",
-  "packageVersion": "0.31.0",
+  "packageVersion": "0.32.0",
   "objects": {
     "@happyvertical/smrt-commerce:ContractCollection": {
       "name": "contractcollection",
@@ -211,6 +211,120 @@
         "version": "c2abc9f0"
       }
     },
+    "@happyvertical/smrt-commerce:ContractLineItemCollection": {
+      "name": "contractlineitemcollection",
+      "className": "ContractLineItemCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:ContractLineItemCollection",
+      "collection": "contractlineitems",
+      "filePath": "/home/runner/_work/smrt/smrt/packages/commerce/src/collections/ContractLineItemCollection.ts",
+      "packageName": "@happyvertical/smrt-commerce",
+      "fields": {},
+      "methods": {
+        "findByContract": {
+          "name": "findByContract",
+          "async": true,
+          "parameters": [
+            {
+              "name": "contractId",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<ContractLineItem[]>",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "findByTenant": {
+          "name": "findByTenant",
+          "async": true,
+          "parameters": [
+            {
+              "name": "tenantId",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<ContractLineItem[]>",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "findGlobal": {
+          "name": "findGlobal",
+          "async": true,
+          "parameters": [],
+          "returnType": "Promise<ContractLineItem[]>",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "findWithGlobals": {
+          "name": "findWithGlobals",
+          "async": true,
+          "parameters": [
+            {
+              "name": "tenantId",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<ContractLineItem[]>",
+          "isStatic": false,
+          "isPublic": true
+        }
+      },
+      "decoratorConfig": {},
+      "extends": "SmrtCollection",
+      "extendsTypeArg": "ContractLineItem",
+      "exportName": "ContractLineItemCollection",
+      "collectionExportName": "ContractLineItemCollectionCollection",
+      "schema": {
+        "tableName": "contract_line_item_collections",
+        "ddl": "CREATE TABLE IF NOT EXISTS \"contract_line_item_collections\" (\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp\n);",
+        "columns": {
+          "id": {
+            "type": "UUID",
+            "primaryKey": true,
+            "referenceKind": "id",
+            "notNull": true
+          },
+          "slug": {
+            "type": "TEXT",
+            "notNull": true
+          },
+          "context": {
+            "type": "TEXT",
+            "notNull": true,
+            "default": ""
+          },
+          "created_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "updated_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          }
+        },
+        "indexes": [
+          {
+            "name": "contract_line_item_collections_id_idx",
+            "columns": [
+              "id"
+            ]
+          },
+          {
+            "name": "contract_line_item_collections_slug_context_idx",
+            "columns": [
+              "slug",
+              "context"
+            ],
+            "unique": true
+          }
+        ],
+        "version": "410887d1"
+      }
+    },
     "@happyvertical/smrt-commerce:CustomerCollection": {
       "name": "customercollection",
       "className": "CustomerCollection",
@@ -557,6 +671,148 @@
         "version": "0cb8f9e1"
       }
     },
+    "@happyvertical/smrt-commerce:FulfillmentLineItemCollection": {
+      "name": "fulfillmentlineitemcollection",
+      "className": "FulfillmentLineItemCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:FulfillmentLineItemCollection",
+      "collection": "fulfillmentlineitems",
+      "filePath": "/home/runner/_work/smrt/smrt/packages/commerce/src/collections/FulfillmentLineItemCollection.ts",
+      "packageName": "@happyvertical/smrt-commerce",
+      "fields": {},
+      "methods": {
+        "findByFulfillment": {
+          "name": "findByFulfillment",
+          "async": true,
+          "parameters": [
+            {
+              "name": "fulfillmentId",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<FulfillmentLineItem[]>",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "findByContractLineItem": {
+          "name": "findByContractLineItem",
+          "async": true,
+          "parameters": [
+            {
+              "name": "contractLineItemId",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<FulfillmentLineItem[]>",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "getTotalFulfilledForContractLine": {
+          "name": "getTotalFulfilledForContractLine",
+          "async": true,
+          "parameters": [
+            {
+              "name": "contractLineItemId",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<number>",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "findByTenant": {
+          "name": "findByTenant",
+          "async": true,
+          "parameters": [
+            {
+              "name": "tenantId",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<FulfillmentLineItem[]>",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "findGlobal": {
+          "name": "findGlobal",
+          "async": true,
+          "parameters": [],
+          "returnType": "Promise<FulfillmentLineItem[]>",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "findWithGlobals": {
+          "name": "findWithGlobals",
+          "async": true,
+          "parameters": [
+            {
+              "name": "tenantId",
+              "type": "string",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<FulfillmentLineItem[]>",
+          "isStatic": false,
+          "isPublic": true
+        }
+      },
+      "decoratorConfig": {},
+      "extends": "SmrtCollection",
+      "extendsTypeArg": "FulfillmentLineItem",
+      "exportName": "FulfillmentLineItemCollection",
+      "collectionExportName": "FulfillmentLineItemCollectionCollection",
+      "schema": {
+        "tableName": "fulfillment_line_item_collections",
+        "ddl": "CREATE TABLE IF NOT EXISTS \"fulfillment_line_item_collections\" (\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp\n);",
+        "columns": {
+          "id": {
+            "type": "UUID",
+            "primaryKey": true,
+            "referenceKind": "id",
+            "notNull": true
+          },
+          "slug": {
+            "type": "TEXT",
+            "notNull": true
+          },
+          "context": {
+            "type": "TEXT",
+            "notNull": true,
+            "default": ""
+          },
+          "created_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "updated_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          }
+        },
+        "indexes": [
+          {
+            "name": "fulfillment_line_item_collections_id_idx",
+            "columns": [
+              "id"
+            ]
+          },
+          {
+            "name": "fulfillment_line_item_collections_slug_context_idx",
+            "columns": [
+              "slug",
+              "context"
+            ],
+            "unique": true
+          }
+        ],
+        "version": "88e7502e"
+      }
+    },
     "@happyvertical/smrt-commerce:InvoiceCollection": {
       "name": "invoicecollection",
       "className": "InvoiceCollection",
@@ -10894,6 +11150,22 @@
         }
       },
       "methods": {
+        "initialize": {
+          "name": "initialize",
+          "async": true,
+          "parameters": [],
+          "returnType": "Promise",
+          "isStatic": false,
+          "isPublic": true
+        },
+        "save": {
+          "name": "save",
+          "async": true,
+          "parameters": [],
+          "returnType": "Promise",
+          "isStatic": false,
+          "isPublic": true
+        },
         "isDelivered": {
           "name": "isDelivered",
           "async": false,
@@ -11133,7 +11405,16 @@
           "default": ""
         }
       },
-      "methods": {},
+      "methods": {
+        "save": {
+          "name": "save",
+          "async": true,
+          "parameters": [],
+          "returnType": "Promise",
+          "isStatic": false,
+          "isPublic": true
+        }
+      },
       "decoratorConfig": {
         "api": {
           "include": [

package/dist/models/Fulfillment.d.ts

@@ -70,6 +70,35 @@ export declare class Fulfillment extends SmrtObject {
      */
     notes: string;
     constructor(options?: any);
+    /**
+     * Capture the status the row was loaded with so the save-time transition
+     * guard can reject illegal status flips made via raw field assignment
+     * (mass-assignment on the generated update route, a stale caller, etc.).
+     * Only persisted rows carry a prior status.
+     */
+    initialize(): Promise<this>;
+    /**
+     * Validate the status transition before persisting, then save. Blocks a
+     * forged `status` written via raw mass-assignment on the open
+     * `api:{create,update}` surface. See S5 audit #1390 follow-up.
+     */
+    save(): Promise<this>;
+    /**
+     * Reject an illegal status flip done via raw assignment. No-op transitions
+     * and brand-new rows are always allowed.
+     */
+    private assertStatusTransition;
+    /**
+     * Resolve the AUTHORITATIVE prior status. The WeakMap is only populated when
+     * {@link initialize} loaded the row; it is empty for an instance built via
+     * `collection.create({ id: <existing>, _skipLoad: true })` (the upsert path
+     * that writes onto an existing row without hydrating it). Trusting an empty
+     * WeakMap there would treat the write as a brand-new row and skip the guard.
+     * So when this instance carries an `id`, read the persisted row straight from
+     * the DB and treat its `status` as the prior. `undefined` = genuinely new.
+     * Mirrors the authoritative-prior-load on Contract/Payment/Invoice/Payout.
+     */
+    private resolvePriorStatus;
     /**
      * Check if fulfillment is complete
      */
@@ -83,15 +112,23 @@ export declare class Fulfillment extends SmrtObject {
      */
     isPending(): boolean;
     /**
-     * Mark as shipped
+     * Assert the current in-memory status may legally transition to `next`,
+     * surfacing the illegal-transition error at the mutation call site rather
+     * than deferring it to save(). A no-op (already in `next`) is allowed.
+     */
+    private assertCanTransitionTo;
+    /**
+     * Mark as shipped. Rejected from a terminal state (DELIVERED / CANCELLED).
      */
     markShipped(trackingNumber?: string, carrier?: string): void;
     /**
-     * Mark as delivered
+     * Mark as delivered. Rejected from CANCELLED (a cancelled shipment can't be
+     * delivered).
      */
     markDelivered(): void;
     /**
-     * Cancel fulfillment
+     * Cancel fulfillment. Rejected once DELIVERED (a delivered shipment can't be
+     * cancelled — model a return/refund elsewhere instead).
      */
     cancel(): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"Fulfillment.d.ts","sourceRoot":"","sources":["../../src/models/Fulfillment.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAExE,OAAO,EACL,KAAK,OAAO,EACZ,iBAAiB,EACjB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAMa,WAAY,SAAQ,UAAU;IACzC;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IACH,eAAe,EAAE,eAAe,CAA4B;IAE5D;;OAEG;IACH,MAAM,EAAE,iBAAiB,CAA6B;IAEtD;;OAEG;IACH,cAAc,EAAE,MAAM,CAAM;IAE5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAM;IAErB;;OAEG;IACH,eAAe,EAAE,OAAO,CAAM;IAE9B;;OAEG;IACH,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE9B;;OAEG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEhC;;OAEG;IACH,iBAAiB,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEtC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IAoB7B;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,WAAW,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAO5D;;OAEG;IACH,aAAa,IAAI,IAAI;IAKrB;;OAEG;IACH,MAAM,IAAI,IAAI;CAGf;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"Fulfillment.d.ts","sourceRoot":"","sources":["../../src/models/Fulfillment.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAExE,OAAO,EACL,KAAK,OAAO,EACZ,iBAAiB,EACjB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAiD3B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAMa,WAAY,SAAQ,UAAU;IACzC;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IACH,eAAe,EAAE,eAAe,CAA4B;IAE5D;;OAEG;IACH,MAAM,EAAE,iBAAiB,CAA6B;IAEtD;;OAEG;IACH,cAAc,EAAE,MAAM,CAAM;IAE5B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAM;IAErB;;OAEG;IACH,eAAe,EAAE,OAAO,CAAM;IAE9B;;OAEG;IACH,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE9B;;OAEG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEhC;;OAEG;IACH,iBAAiB,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEtC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IAoB7B;;;;;OAKG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ1C;;;;OAIG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQpC;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAa9B;;;;;;;;;OASG;YACW,kBAAkB;IAchC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;OAEG;IACH,WAAW,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ5D;;;OAGG;IACH,aAAa,IAAI,IAAI;IAMrB;;;OAGG;IACH,MAAM,IAAI,IAAI;CAIf;AAED,eAAe,WAAW,CAAC"}

package/dist/models/FulfillmentLineItem.d.ts

@@ -37,6 +37,30 @@ export declare class FulfillmentLineItem extends SmrtObject {
      */
     notes: string;
     constructor(options?: any);
+    /**
+     * Save-time over-fulfillment guard (S5 audit #1390 follow-up, round 2):
+     *  - `quantityFulfilled` must be a finite, positive number,
+     *  - the referenced `ContractLineItem` must resolve **within the caller's
+     *    tenant scope** AND belong to the same contract as the parent
+     *    Fulfillment, and
+     *  - the sum of all FulfillmentLineItems against that ContractLineItem
+     *    (this row included) must not exceed the ordered `ContractLineItem.quantity`.
+     *
+     * Without this, a caller could ship 50 of 10 ordered — the direct parallel
+     * to the PaymentAllocation over-allocation hole #1390 closed.
+     *
+     * Tenant isolation (round 2): the ContractLineItem is loaded through
+     * `ContractLineItemCollection`, so it goes through the tenancy
+     * auto-filtering interceptors. A cross-tenant `contractLineItemId` therefore
+     * fails closed — it resolves to `null` and trips the existing "does not
+     * exist" error rather than leaking a foreign-tenant ordered quantity. The
+     * raw `this.db.get('contract_line_items', …)` it replaced bypassed those
+     * filters. We additionally load the parent Fulfillment (also tenant-scoped)
+     * and reject when the line item belongs to a *different* contract than the
+     * Fulfillment is fulfilling, so a valid-but-unrelated line id can't be
+     * used to fulfill against the wrong order.
+     */
+    save(): Promise<this>;
 }
 export default FulfillmentLineItem;
 //# sourceMappingURL=FulfillmentLineItem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"FulfillmentLineItem.d.ts","sourceRoot":"","sources":["../../src/models/FulfillmentLineItem.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAGxE;;;;;;;;;;;;;;GAcG;AACH,qBAMa,mBAAoB,SAAQ,UAAU;IACjD;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,aAAa,EAAE,MAAM,CAAM;IAE3B;;OAEG;IAEH,kBAAkB,EAAE,MAAM,CAAM;IAEhC;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAO;IAEhC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;CAW9B;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"FulfillmentLineItem.d.ts","sourceRoot":"","sources":["../../src/models/FulfillmentLineItem.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAUxE;;;;;;;;;;;;;;GAcG;AACH,qBAMa,mBAAoB,SAAQ,UAAU;IACjD;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,aAAa,EAAE,MAAM,CAAM;IAE3B;;OAEG;IAEH,kBAAkB,EAAE,MAAM,CAAM;IAEhC;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAO;IAEhC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IAY7B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAwFrC;AAED,eAAe,mBAAmB,CAAC"}

package/dist/models/Invoice.d.ts

@@ -190,6 +190,31 @@ export declare class Invoice extends SmrtObject {
      * (the dynamic imports stay inside the package).
      */
     private recomputeAmountsForSave;
+    /**
+     * Whether `amountPaid` covers `totalAmount` within the sub-cent rounding
+     * tolerance. This is the SINGLE source of truth for the **PAID** decision —
+     * both {@link updatePaymentStatus} (which decides PAID) and
+     * {@link assertPaymentStatusConsistent} (which validates PAID on save) call
+     * it, so the PAID-deciding comparison and the PAID-validating comparison can
+     * never drift apart. A strict `amountPaid >= totalAmount` here would diverge
+     * from the epsilon-tolerant guard: a float-summed total paid exactly (e.g.
+     * `0.1 × 3` line items paid `0.3`) reads as "not covered" by `>=` but
+     * "covered" by the guard, so `updatePaymentStatus` would set PARTIAL and the
+     * save-time guard would then reject it — leaving a genuinely-paid invoice
+     * unsaveable (S5 audit #1390 follow-up).
+     *
+     * NOTE: the claim is scoped to PAID. The PARTIAL branch is NOT unified the
+     * same way — {@link updatePaymentStatus} treats any `amountPaid > 0` as
+     * PARTIAL, whereas {@link isPartiallyPaid} (used by the save-time guard)
+     * requires `amountPaid > INVOICE_EPSILON`. That pre-existing asymmetry only
+     * matters for a sub-cent dust payment and is intentionally left as-is.
+     */
+    private isFullyPaid;
+    /**
+     * Whether `amountPaid` is a non-trivial partial payment of `totalAmount`.
+     * Derived from {@link isFullyPaid} so the two stay mutually exclusive.
+     */
+    private isPartiallyPaid;
     /**
      * After amounts are recomputed and amountPaid is re-derived from allocations,
      * assert the persisted `status` is consistent with the derived
@@ -205,8 +230,19 @@ export declare class Invoice extends SmrtObject {
      */
     private assertPaymentStatusConsistent;
     /**
-     * Enforce `totalAmount === subtotal + taxAmount` (within rounding tolerance).
-     * Used when the invoice has no line items to recompute from.
+     * Enforce `totalAmount === subtotal + taxAmount` (within rounding tolerance),
+     * then SNAP `totalAmount` to the exact arithmetic. Used when the invoice has
+     * no line items to recompute from.
+     *
+     * The snap closes the invoice-vs-ledger epsilon gap (S5 audit #1390
+     * follow-up): the invoice guard tolerates `INVOICE_EPSILON` (0.01) but the
+     * smrt-ledgers balance check uses a tighter `BALANCE_EPSILON` (0.001). A
+     * no-line-item invoice with, say, subtotal 100.00 / total 100.005 passes this
+     * guard, yet `recognizeRevenue` would build DR 100.005 / CR 100.00 and
+     * `journal.post()` would reject it as unbalanced — voiding the journal and
+     * permanently blocking revenue recognition. Snapping `totalAmount` to
+     * `subtotal + taxAmount` here (after the tolerance check) means the persisted
+     * total and every journal built from it are always ledger-consistent.
      */
     private assertTotalArithmetic;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"Invoice.d.ts","sourceRoot":"","sources":["../../src/models/Invoice.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Invoice.d.ts","sourceRoot":"","sources":["../../src/models/Invoice.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,KAAK,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AA0FhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAwCa,OAAQ,SAAQ,UAAU;IACrC;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IAEH,UAAU,EAAE,MAAM,CAAM;IAMxB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAM;IAE3B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAM;IAMvB;;OAEG;IACH,SAAS,EAAE,IAAI,CAAc;IAE7B;;OAEG;IACH,OAAO,EAAE,IAAI,CAAc;IAE3B;;OAEG;IACH,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAQ;IAM7B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAK;IAErB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAK;IAEtB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAK;IAExB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAK;IAEvB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAS;IAMzB;;OAEG;IACH,MAAM,EAAE,aAAa,CAAuB;IAM5C;;OAEG;IAEH,WAAW,EAAE,MAAM,CAAM;IAEzB;;OAEG;IAEH,gBAAgB,EAAE,MAAM,CAAM;IAM9B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAM;IAExB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAM;IAEhC;;OAEG;IACH,gBAAgB,EAAE,MAAM,CAAM;IAE9B;;OAEG;IACH,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAQ;IAM7B;;OAEG;IACH,MAAM,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE3B;;OAEG;IACH,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE7B;;OAEG;IACH,aAAa,EAAE,MAAM,CAAK;IAE1B;;OAEG;IACH,cAAc,EAAE,IAAI,GAAG,IAAI,CAAQ;IAMnC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;IAEnB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAM;IAE3B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IAwC7B;;;;;;;OAOG;IACY,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY1C;;;;;;;;;;;;;;;;;OAiBG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBpC;;;;;;;;OAQG;YACW,kBAAkB;IAgBhC;;;;;OAKG;YACW,uBAAuB;IAyErC;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,WAAW;IAInB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,6BAA6B;IAmCrC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAqBhC;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAiB9B;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,SAAS,IAAI,OAAO;IAMpB;;OAEG;IACH,YAAY,IAAI,MAAM;IAQtB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAUhB;;;;;;;OAOG;IACH,UAAU,IAAI,IAAI;IAQlB;;;;;;;OAOG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAgC7C;;OAEG;IACH,MAAM,IAAI,IAAI;IASd;;OAEG;IACH,QAAQ,IAAI,IAAI;IAQhB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC;IA8FtE;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAiBzC;;;;;;;;;;;;;;;;;OAiBG;IACG,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC;CA4BxC;AAED,eAAe,OAAO,CAAC"}

package/dist/models/PaymentAllocation.d.ts

@@ -72,12 +72,14 @@ export declare class PaymentAllocation extends SmrtObject {
     notes: string;
     constructor(options?: any);
     /**
-     * Save-time integrity guard (S5 audit #1390):
-     *  - allocation `amount` must be a finite, positive number, and
+     * Save-time integrity guard (S5 audit #1390 + follow-up):
+     *  - allocation `amount` must be a finite, positive number,
      *  - the sum of all allocations against the referenced Payment (this row
      *    included) must not exceed the Payment's amount — over-applying a
      *    payment across invoices would falsify both payment and invoice
-     *    balances.
+     *    balances, and
+     *  - the sum of all allocations against the referenced Invoice (this row
+     *    included) must not exceed the Invoice's `totalAmount`.
      *
      * The Payment-amount cap is enforced against the persisted Payment row. An
      * allocation always carries a `@foreignKey('Payment')` paymentId, so a
@@ -86,6 +88,16 @@ export declare class PaymentAllocation extends SmrtObject {
      * entirely, letting a caller over-apply (or fabricate) funds simply by
      * pointing at a non-existent payment. An empty `paymentId` is still rejected
      * by the underlying FK requirement; the positivity check always applies.
+     *
+     * The Invoice-total cap (follow-up) closes a complementary hole: the
+     * per-Payment cap lets allocations from *different* payments each pass their
+     * own check while jointly summing above the invoice total. The next
+     * `Invoice.save()` would then recompute `amountPaid` from these allocations,
+     * trip `assertNonNegativeAmounts` (amountPaid > totalAmount), and leave the
+     * invoice permanently unsaveable while the over-allocations persist. Capping
+     * here keeps allocations from ever exceeding what the invoice owes. The cap
+     * is skipped only when the invoice row can't be resolved (e.g. ledger-less /
+     * not-yet-persisted) so it never blocks an otherwise-valid allocation.
      */
     save(): Promise<this>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"PaymentAllocation.d.ts","sourceRoot":"","sources":["../../src/models/PaymentAllocation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AASxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAoBa,iBAAkB,SAAQ,UAAU;IAC/C;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAK;IAEnB;;OAEG;IACH,WAAW,EAAE,IAAI,CAAc;IAE/B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAM;IAEzB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IAa7B;;;;;;;;;;;;;;;OAeG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA0CrC;AAED,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"PaymentAllocation.d.ts","sourceRoot":"","sources":["../../src/models/PaymentAllocation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAc,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AASxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAoBa,iBAAkB,SAAQ,UAAU;IAC/C;;;OAGG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAK;IAEnB;;OAEG;IACH,WAAW,EAAE,IAAI,CAAc;IAE/B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAM;IAEzB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAM;gBAEP,OAAO,GAAE,GAAQ;IAa7B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAmFrC;AAED,eAAe,iBAAiB,CAAC"}

package/dist/smrt-knowledge.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-06-23T03:03:13.154Z",
+  "generatedAt": "2026-06-23T07:09:06.841Z",
   "packageName": "@happyvertical/smrt-commerce",
-  "packageVersion": "0.31.0",
+  "packageVersion": "0.32.0",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "3f11b5f204fd20ef05d782d5e2d9a19426e02c66e24d9f3dd8318c85992414cf",
-    "packageJson": "30c69b8574c3e033401f9f8362f3374840a59e60d719c672de9bb964741ab660",
+    "manifest": "84f8fdc2826f300da47a9ab3762a862193a80a2dcb3e347c4ab578e5b40a81ef",
+    "packageJson": "941964662329b4dd0a86529d6edfa8f2f11e0adf215f3ba4d55e74009aec8d99",
     "agents": "f544ac9cece5c94aaead6013316709fcd044944b993110fc7218c0db7c998a63"
   },
   "exports": [
@@ -76,6 +76,28 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "ContractLineItemCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:ContractLineItemCollection",
+      "collection": "contractlineitems",
+      "tableName": "contract_line_item_collections",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByContract",
+        "findByTenant",
+        "findGlobal",
+        "findWithGlobals"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "CustomerCollection",
       "qualifiedName": "@happyvertical/smrt-commerce:CustomerCollection",
@@ -129,6 +151,30 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "FulfillmentLineItemCollection",
+      "qualifiedName": "@happyvertical/smrt-commerce:FulfillmentLineItemCollection",
+      "collection": "fulfillmentlineitems",
+      "tableName": "fulfillment_line_item_collections",
+      "packageName": "@happyvertical/smrt-commerce",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByContractLineItem",
+        "findByFulfillment",
+        "findByTenant",
+        "findGlobal",
+        "findWithGlobals",
+        "getTotalFulfilledForContractLine"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "InvoiceCollection",
       "qualifiedName": "@happyvertical/smrt-commerce:InvoiceCollection",
@@ -2919,11 +2965,13 @@
       ],
       "methods": [
         "cancel",
+        "initialize",
         "isDelivered",
         "isInTransit",
         "isPending",
         "markDelivered",
-        "markShipped"
+        "markShipped",
+        "save"
       ],
       "surfaces": [
         {
@@ -3065,7 +3113,9 @@
           "columnType": "UUID"
         }
       ],
-      "methods": [],
+      "methods": [
+        "save"
+      ],
       "surfaces": [
         {
           "kind": "api",
@@ -5488,7 +5538,7 @@
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 91
+    "uuidColumns": 93
   },
   "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- **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- **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"
 }