@happyvertical/smrt-commerce 0.30.0 → 0.31.1

package/dist/index.js

@@ -1081,6 +1081,178 @@ class ContractCollection extends SmrtCollection {
     );
   }
 }
+var __defProp$8 = Object.defineProperty;
+var __getOwnPropDesc$8 = Object.getOwnPropertyDescriptor;
+var __decorateClass$8 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$8(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$8(target, key, result);
+  return result;
+};
+let ContractLineItem = class extends SmrtObject {
+  tenantId = null;
+  contractId = "";
+  /**
+   * Item description
+   */
+  description = "";
+  /**
+   * Quantity ordered
+   */
+  quantity = 1;
+  /**
+   * Unit price before discount
+   */
+  unitPrice = 0;
+  /**
+   * Discount amount (flat, not percentage)
+   */
+  discount = 0;
+  /**
+   * Tax rate as decimal (e.g., 0.08 for 8%)
+   */
+  taxRate = 0;
+  /**
+   * Calculated line amount (qty * price - discount + tax)
+   */
+  amount = 0;
+  productId = "";
+  /**
+   * SKU or item code
+   */
+  sku = "";
+  /**
+   * Start date (for lease/subscription items)
+   */
+  startDate = null;
+  /**
+   * End date (for lease/subscription items)
+   */
+  endDate = null;
+  /**
+   * Billing period (for subscriptions: 'monthly', 'yearly', etc.)
+   */
+  billingPeriod = "";
+  /**
+   * Sort order within the contract
+   */
+  sortOrder = 0;
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.contractId !== void 0) this.contractId = options.contractId;
+    if (options.description !== void 0)
+      this.description = options.description;
+    if (options.quantity !== void 0) this.quantity = options.quantity;
+    if (options.unitPrice !== void 0) this.unitPrice = options.unitPrice;
+    if (options.discount !== void 0) this.discount = options.discount;
+    if (options.taxRate !== void 0) this.taxRate = options.taxRate;
+    if (options.amount !== void 0) this.amount = options.amount;
+    if (options.productId !== void 0) this.productId = options.productId;
+    if (options.sku !== void 0) this.sku = options.sku;
+    if (options.startDate !== void 0) this.startDate = options.startDate;
+    if (options.endDate !== void 0) this.endDate = options.endDate;
+    if (options.billingPeriod !== void 0)
+      this.billingPeriod = options.billingPeriod;
+    if (options.sortOrder !== void 0) this.sortOrder = options.sortOrder;
+  }
+  /**
+   * Calculate the line amount
+   */
+  calculateAmount() {
+    const subtotal = this.quantity * this.unitPrice - this.discount;
+    const tax = subtotal * this.taxRate;
+    return subtotal + tax;
+  }
+  /**
+   * Check if this is a subscription/recurring item
+   */
+  isRecurring() {
+    return !!this.billingPeriod && !!this.startDate;
+  }
+  /**
+   * Check if subscription is active
+   */
+  isSubscriptionActive() {
+    if (!this.isRecurring()) return false;
+    if (!this.startDate) return false;
+    const now = /* @__PURE__ */ new Date();
+    if (now < this.startDate) return false;
+    if (this.endDate && now > this.endDate) return false;
+    return true;
+  }
+};
+__decorateClass$8([
+  tenantId({ nullable: true })
+], ContractLineItem.prototype, "tenantId", 2);
+__decorateClass$8([
+  foreignKey("Contract")
+], ContractLineItem.prototype, "contractId", 2);
+__decorateClass$8([
+  crossPackageRef("@happyvertical/smrt-products:Product")
+], ContractLineItem.prototype, "productId", 2);
+ContractLineItem = __decorateClass$8([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableStrategy: "sti",
+    api: { include: ["list", "get", "create", "update", "delete"] },
+    mcp: { include: ["list", "get"] },
+    cli: true
+  })
+], ContractLineItem);
+class ContractLineItemCollection extends SmrtCollection {
+  static _itemClass = ContractLineItem;
+  /**
+   * Find contract line items by their parent contract.
+   *
+   * @param contractId - Contract ID
+   * @returns Array of contract line items, sorted by sortOrder
+   */
+  async findByContract(contractId) {
+    return await this.list({
+      where: { contractId },
+      orderBy: "sortOrder ASC"
+    });
+  }
+  // ============================================================================
+  // Tenant Helper Methods
+  // ============================================================================
+  /**
+   * Find all contract line items belonging to a specific tenant
+   *
+   * @param tenantId - Tenant ID
+   * @returns Array of contract line items for the tenant
+   */
+  async findByTenant(tenantId2) {
+    return this.list({ where: { tenantId: tenantId2 } });
+  }
+  /**
+   * Find all global contract line items (not associated with any tenant)
+   *
+   * @returns Array of global contract line items
+   */
+  async findGlobal() {
+    return this.list({ where: { tenantId: null } });
+  }
+  /**
+   * Find contract line items for a tenant including global line items
+   *
+   * @param tenantId - Tenant ID
+   * @returns Array of tenant-specific and global contract line items
+   */
+  async findWithGlobals(tenantId2) {
+    return this.query(
+      `SELECT * FROM ${this.tableName} WHERE tenant_id = ? OR tenant_id IS NULL`,
+      [tenantId2]
+    );
+  }
+}
+const ContractLineItemCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  ContractLineItemCollection
+}, Symbol.toStringTag, { value: "Module" }));
 class CustomerCollection extends SmrtCollection {
   static _itemClass = Customer;
   /**
@@ -1172,16 +1344,37 @@ class CustomerCollection extends SmrtCollection {
     );
   }
 }
-var __defProp$8 = Object.defineProperty;
-var __getOwnPropDesc$8 = Object.getOwnPropertyDescriptor;
-var __decorateClass$8 = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$8(target, key) : target;
+var __defProp$7 = Object.defineProperty;
+var __getOwnPropDesc$7 = Object.getOwnPropertyDescriptor;
+var __decorateClass$7 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$7(target, key) : target;
   for (var i = decorators.length - 1, decorator; i >= 0; i--)
     if (decorator = decorators[i])
       result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp$8(target, key, result);
+  if (kind && result) __defProp$7(target, key, result);
   return result;
 };
+const FULFILLMENT_STATUS_TRANSITIONS = {
+  [FulfillmentStatus.PENDING]: [
+    FulfillmentStatus.PROCESSING,
+    FulfillmentStatus.SHIPPED,
+    FulfillmentStatus.DELIVERED,
+    FulfillmentStatus.CANCELLED
+  ],
+  [FulfillmentStatus.PROCESSING]: [
+    FulfillmentStatus.SHIPPED,
+    FulfillmentStatus.DELIVERED,
+    FulfillmentStatus.CANCELLED
+  ],
+  [FulfillmentStatus.SHIPPED]: [
+    FulfillmentStatus.DELIVERED,
+    FulfillmentStatus.CANCELLED
+  ],
+  // Terminal states: no outbound transitions.
+  [FulfillmentStatus.DELIVERED]: [],
+  [FulfillmentStatus.CANCELLED]: []
+};
+const loadedFulfillmentStatus = /* @__PURE__ */ new WeakMap();
 let Fulfillment = class extends SmrtObject {
   tenantId = null;
   contractId = "";
@@ -1240,6 +1433,67 @@ let Fulfillment = class extends SmrtObject {
       this.estimatedDelivery = options.estimatedDelivery;
     if (options.notes !== void 0) this.notes = options.notes;
   }
+  /**
+   * 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.
+   */
+  async initialize() {
+    await super.initialize();
+    if (await this.isSaved()) {
+      loadedFulfillmentStatus.set(this, this.status);
+    }
+    return 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.
+   */
+  async save() {
+    const prior = await this.resolvePriorStatus();
+    this.assertStatusTransition(prior);
+    const result = await super.save();
+    loadedFulfillmentStatus.set(this, this.status);
+    return result;
+  }
+  /**
+   * Reject an illegal status flip done via raw assignment. No-op transitions
+   * and brand-new rows are always allowed.
+   */
+  assertStatusTransition(prior) {
+    if (prior === void 0) return;
+    if (prior === this.status) return;
+    const allowed = FULFILLMENT_STATUS_TRANSITIONS[prior] ?? [];
+    if (!allowed.includes(this.status)) {
+      throw new Error(
+        `Fulfillment ${this.trackingNumber || this.id}: illegal status transition '${prior}' → '${this.status}'. Use the guarded helpers (markShipped / markDelivered / cancel).`
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  async resolvePriorStatus() {
+    if (this.id) {
+      try {
+        const row = await this.db.get(this.tableName, { id: this.id });
+        if (row && row.status != null) {
+          return row.status;
+        }
+      } catch {
+      }
+    }
+    return loadedFulfillmentStatus.get(this);
+  }
   /**
    * Check if fulfillment is complete
    */
@@ -1259,35 +1513,54 @@ let Fulfillment = class extends SmrtObject {
     return this.status === FulfillmentStatus.PENDING;
   }
   /**
-   * 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.
+   */
+  assertCanTransitionTo(next) {
+    if (this.status === next) return;
+    const allowed = FULFILLMENT_STATUS_TRANSITIONS[this.status] ?? [];
+    if (!allowed.includes(next)) {
+      throw new Error(
+        `Fulfillment ${this.trackingNumber || this.id || "<new>"}: cannot move from '${this.status}' to '${next}'.`
+      );
+    }
+  }
+  /**
+   * Mark as shipped. Rejected from a terminal state (DELIVERED / CANCELLED).
    */
   markShipped(trackingNumber, carrier) {
+    this.assertCanTransitionTo(FulfillmentStatus.SHIPPED);
     this.status = FulfillmentStatus.SHIPPED;
     this.shippedAt = /* @__PURE__ */ new Date();
     if (trackingNumber) this.trackingNumber = trackingNumber;
     if (carrier) this.carrier = carrier;
   }
   /**
-   * Mark as delivered
+   * Mark as delivered. Rejected from CANCELLED (a cancelled shipment can't be
+   * delivered).
    */
   markDelivered() {
+    this.assertCanTransitionTo(FulfillmentStatus.DELIVERED);
     this.status = FulfillmentStatus.DELIVERED;
     this.deliveredAt = /* @__PURE__ */ new Date();
   }
   /**
-   * Cancel fulfillment
+   * Cancel fulfillment. Rejected once DELIVERED (a delivered shipment can't be
+   * cancelled — model a return/refund elsewhere instead).
    */
   cancel() {
+    this.assertCanTransitionTo(FulfillmentStatus.CANCELLED);
     this.status = FulfillmentStatus.CANCELLED;
   }
 };
-__decorateClass$8([
+__decorateClass$7([
   tenantId({ nullable: true })
 ], Fulfillment.prototype, "tenantId", 2);
-__decorateClass$8([
+__decorateClass$7([
   foreignKey("Contract")
 ], Fulfillment.prototype, "contractId", 2);
-Fulfillment = __decorateClass$8([
+Fulfillment = __decorateClass$7([
   TenantScoped({ mode: "optional" }),
   smrt({
     api: { include: ["list", "get", "create", "update"] },
@@ -1411,14 +1684,218 @@ class FulfillmentCollection extends SmrtCollection {
     );
   }
 }
-var __defProp$7 = Object.defineProperty;
-var __getOwnPropDesc$7 = Object.getOwnPropertyDescriptor;
-var __decorateClass$7 = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$7(target, key) : target;
+const FulfillmentCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  FulfillmentCollection
+}, Symbol.toStringTag, { value: "Module" }));
+var __defProp$6 = Object.defineProperty;
+var __getOwnPropDesc$6 = Object.getOwnPropertyDescriptor;
+var __decorateClass$6 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$6(target, key) : target;
   for (var i = decorators.length - 1, decorator; i >= 0; i--)
     if (decorator = decorators[i])
       result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp$7(target, key, result);
+  if (kind && result) __defProp$6(target, key, result);
+  return result;
+};
+const FULFILLMENT_QUANTITY_EPSILON = 0.01;
+let FulfillmentLineItem = class extends SmrtObject {
+  tenantId = null;
+  fulfillmentId = "";
+  contractLineItemId = "";
+  /**
+   * Quantity fulfilled in this fulfillment
+   */
+  quantityFulfilled = 1;
+  /**
+   * Notes about this line item
+   */
+  notes = "";
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.fulfillmentId !== void 0)
+      this.fulfillmentId = options.fulfillmentId;
+    if (options.contractLineItemId !== void 0)
+      this.contractLineItemId = options.contractLineItemId;
+    if (options.quantityFulfilled !== void 0)
+      this.quantityFulfilled = options.quantityFulfilled;
+    if (options.notes !== void 0) this.notes = options.notes;
+  }
+  /**
+   * 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.
+   */
+  async save() {
+    if (!Number.isFinite(this.quantityFulfilled) || this.quantityFulfilled <= 0) {
+      throw new Error(
+        `FulfillmentLineItem ${this.id ?? "<new>"}: quantityFulfilled must be a positive number (got ${this.quantityFulfilled}).`
+      );
+    }
+    if (this.contractLineItemId) {
+      const { ContractLineItemCollection: ContractLineItemCollection2 } = await Promise.resolve().then(() => ContractLineItemCollection$1);
+      const lineItems = await ContractLineItemCollection2.create(
+        this.options
+      );
+      const orderedLineItem = await lineItems.get(this.contractLineItemId);
+      if (!orderedLineItem) {
+        throw new Error(
+          `FulfillmentLineItem ${this.id ?? "<new>"}: referenced ContractLineItem '${this.contractLineItemId}' does not exist — refusing to fulfill against a missing line item (the over-fulfillment cap cannot be enforced otherwise).`
+        );
+      }
+      if (this.fulfillmentId) {
+        const { FulfillmentCollection: FulfillmentCollection2 } = await Promise.resolve().then(() => FulfillmentCollection$1);
+        const fulfillments = await FulfillmentCollection2.create(
+          this.options
+        );
+        const fulfillment = await fulfillments.get(this.fulfillmentId);
+        if (fulfillment && orderedLineItem.contractId !== fulfillment.contractId) {
+          throw new Error(
+            `FulfillmentLineItem ${this.id ?? "<new>"}: ContractLineItem '${this.contractLineItemId}' belongs to contract '${orderedLineItem.contractId}', but its Fulfillment '${this.fulfillmentId}' fulfills contract '${fulfillment.contractId}' — refusing to fulfill a line item from a different contract.`
+          );
+        }
+      }
+      const ordered = Number(orderedLineItem.quantity);
+      const { FulfillmentLineItemCollection: FulfillmentLineItemCollection2 } = await Promise.resolve().then(() => FulfillmentLineItemCollection$1);
+      const siblings = await FulfillmentLineItemCollection2.create(
+        this.options
+      );
+      const existing = await siblings.findByContractLineItem(
+        this.contractLineItemId
+      );
+      const otherFulfilled = existing.reduce(
+        (sum, item) => item.id === this.id ? sum : sum + item.quantityFulfilled,
+        0
+      );
+      if (Number.isFinite(ordered) && otherFulfilled + this.quantityFulfilled - ordered > FULFILLMENT_QUANTITY_EPSILON) {
+        throw new Error(
+          `FulfillmentLineItem ${this.id ?? "<new>"}: fulfilling ${this.quantityFulfilled} would over-fulfill contract line '${this.contractLineItemId}' — already fulfilled ${otherFulfilled} of ${ordered} ordered.`
+        );
+      }
+    }
+    return super.save();
+  }
+};
+__decorateClass$6([
+  tenantId({ nullable: true })
+], FulfillmentLineItem.prototype, "tenantId", 2);
+__decorateClass$6([
+  foreignKey("Fulfillment")
+], FulfillmentLineItem.prototype, "fulfillmentId", 2);
+__decorateClass$6([
+  foreignKey("ContractLineItem")
+], FulfillmentLineItem.prototype, "contractLineItemId", 2);
+FulfillmentLineItem = __decorateClass$6([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    api: { include: ["list", "get", "create", "update", "delete"] },
+    mcp: { include: ["list", "get"] },
+    cli: true
+  })
+], FulfillmentLineItem);
+class FulfillmentLineItemCollection extends SmrtCollection {
+  static _itemClass = FulfillmentLineItem;
+  /**
+   * Find fulfillment line items by their parent fulfillment.
+   *
+   * @param fulfillmentId - Fulfillment ID
+   * @returns Array of fulfillment line items
+   */
+  async findByFulfillment(fulfillmentId) {
+    return await this.list({
+      where: { fulfillmentId },
+      orderBy: "created_at DESC"
+    });
+  }
+  /**
+   * Find every fulfillment line item that fulfills a given contract line item,
+   * across all fulfillments. Used by the over-fulfillment cap to sum how much
+   * of an ordered line has already been fulfilled.
+   *
+   * @param contractLineItemId - Contract line item ID
+   * @returns Array of fulfillment line items targeting that contract line
+   */
+  async findByContractLineItem(contractLineItemId) {
+    return await this.list({
+      where: { contractLineItemId },
+      orderBy: "created_at DESC"
+    });
+  }
+  /**
+   * Sum the quantity already fulfilled for a contract line item across all
+   * fulfillments.
+   *
+   * @param contractLineItemId - Contract line item ID
+   * @returns Total quantity fulfilled
+   */
+  async getTotalFulfilledForContractLine(contractLineItemId) {
+    const items = await this.findByContractLineItem(contractLineItemId);
+    return items.reduce((sum, item) => sum + item.quantityFulfilled, 0);
+  }
+  // ============================================================================
+  // Tenant Helper Methods
+  // ============================================================================
+  /**
+   * Find all fulfillment line items belonging to a specific tenant
+   *
+   * @param tenantId - Tenant ID
+   * @returns Array of fulfillment line items for the tenant
+   */
+  async findByTenant(tenantId2) {
+    return this.list({ where: { tenantId: tenantId2 } });
+  }
+  /**
+   * Find all global fulfillment line items (not associated with any tenant)
+   *
+   * @returns Array of global fulfillment line items
+   */
+  async findGlobal() {
+    return this.list({ where: { tenantId: null } });
+  }
+  /**
+   * Find fulfillment line items for a tenant including global line items
+   *
+   * @param tenantId - Tenant ID
+   * @returns Array of tenant-specific and global fulfillment line items
+   */
+  async findWithGlobals(tenantId2) {
+    return this.query(
+      `SELECT * FROM ${this.tableName} WHERE tenant_id = ? OR tenant_id IS NULL`,
+      [tenantId2]
+    );
+  }
+}
+const FulfillmentLineItemCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  FulfillmentLineItemCollection
+}, Symbol.toStringTag, { value: "Module" }));
+var __defProp$5 = Object.defineProperty;
+var __getOwnPropDesc$5 = Object.getOwnPropertyDescriptor;
+var __decorateClass$5 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$5(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$5(target, key, result);
   return result;
 };
 const INVOICE_EPSILON = 0.01;
@@ -1742,6 +2219,35 @@ let Invoice = class extends SmrtObject {
       }
     }
   }
+  /**
+   * 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.
+   */
+  isFullyPaid() {
+    return this.amountPaid - this.totalAmount >= -INVOICE_EPSILON;
+  }
+  /**
+   * Whether `amountPaid` is a non-trivial partial payment of `totalAmount`.
+   * Derived from {@link isFullyPaid} so the two stay mutually exclusive.
+   */
+  isPartiallyPaid() {
+    return this.amountPaid > INVOICE_EPSILON && !this.isFullyPaid();
+  }
   /**
    * After amounts are recomputed and amountPaid is re-derived from allocations,
    * assert the persisted `status` is consistent with the derived
@@ -1757,8 +2263,8 @@ let Invoice = class extends SmrtObject {
    */
   assertPaymentStatusConsistent() {
     const label = this.invoiceNumber || this.id || "<new>";
-    const fullyPaid = this.amountPaid - this.totalAmount >= -INVOICE_EPSILON;
-    const partiallyPaid = this.amountPaid > INVOICE_EPSILON && !fullyPaid;
+    const fullyPaid = this.isFullyPaid();
+    const partiallyPaid = this.isPartiallyPaid();
     if (this.status === InvoiceStatus.PAID && !fullyPaid) {
       throw new Error(
         `Invoice ${label}: status is PAID but derived amountPaid ${this.amountPaid} does not cover totalAmount ${this.totalAmount}. Payment status is derived from PaymentAllocations — use updatePaymentStatus().`
@@ -1776,8 +2282,19 @@ let Invoice = class extends SmrtObject {
     }
   }
   /**
-   * 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.
    */
   assertTotalArithmetic() {
     const expected = this.subtotal + this.taxAmount;
@@ -1786,6 +2303,7 @@ let Invoice = class extends SmrtObject {
         `Invoice ${this.invoiceNumber || this.id || "<new>"}: totalAmount ${this.totalAmount} must equal subtotal + taxAmount (${expected}).`
       );
     }
+    this.totalAmount = expected;
   }
   /**
    * Reject negative financial values and an amountPaid that exceeds the total
@@ -1911,7 +2429,7 @@ let Invoice = class extends SmrtObject {
     if (this.status === InvoiceStatus.CANCELLED || this.status === InvoiceStatus.WRITTEN_OFF) {
       return;
     }
-    if (amountPaid >= this.totalAmount) {
+    if (this.isFullyPaid()) {
       this.status = InvoiceStatus.PAID;
       this.paidDate = /* @__PURE__ */ new Date();
     } else if (amountPaid > 0) {
@@ -2092,22 +2610,22 @@ let Invoice = class extends SmrtObject {
     };
   }
 };
-__decorateClass$7([
+__decorateClass$5([
   tenantId({ nullable: true })
 ], Invoice.prototype, "tenantId", 2);
-__decorateClass$7([
+__decorateClass$5([
   foreignKey("Customer")
 ], Invoice.prototype, "customerId", 2);
-__decorateClass$7([
+__decorateClass$5([
   foreignKey("Contract")
 ], Invoice.prototype, "contractId", 2);
-__decorateClass$7([
+__decorateClass$5([
   crossPackageRef("@happyvertical/smrt-ledgers:Journal")
 ], Invoice.prototype, "arJournalId", 2);
-__decorateClass$7([
+__decorateClass$5([
   crossPackageRef("@happyvertical/smrt-ledgers:Journal")
 ], Invoice.prototype, "revenueJournalId", 2);
-Invoice = __decorateClass$7([
+Invoice = __decorateClass$5([
   TenantScoped({ mode: "optional" }),
   smrt({
     // ROOT FIX (S5 audit #1390 round 4): the generated create/update surface may
@@ -2398,17 +2916,22 @@ class InvoiceCollection extends SmrtCollection {
     return this.query(
       `SELECT * FROM ${this.tableName} WHERE tenant_id = ? OR tenant_id IS NULL`,
       [tenantId2]
-    );
-  }
-}
-var __defProp$6 = Object.defineProperty;
-var __getOwnPropDesc$6 = Object.getOwnPropertyDescriptor;
-var __decorateClass$6 = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$6(target, key) : target;
+    );
+  }
+}
+const InvoiceCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  InvoiceCollection,
+  UNPAID_STATUSES
+}, Symbol.toStringTag, { value: "Module" }));
+var __defProp$4 = Object.defineProperty;
+var __getOwnPropDesc$4 = Object.getOwnPropertyDescriptor;
+var __decorateClass$4 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$4(target, key) : target;
   for (var i = decorators.length - 1, decorator; i >= 0; i--)
     if (decorator = decorators[i])
       result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp$6(target, key, result);
+  if (kind && result) __defProp$4(target, key, result);
   return result;
 };
 let InvoiceLineItem = class extends SmrtObject {
@@ -2543,16 +3066,16 @@ let InvoiceLineItem = class extends SmrtObject {
     };
   }
 };
-__decorateClass$6([
+__decorateClass$4([
   tenantId({ nullable: true })
 ], InvoiceLineItem.prototype, "tenantId", 2);
-__decorateClass$6([
+__decorateClass$4([
   foreignKey("Invoice")
 ], InvoiceLineItem.prototype, "invoiceId", 2);
-__decorateClass$6([
+__decorateClass$4([
   crossPackageRef("@happyvertical/smrt-ledgers:Account")
 ], InvoiceLineItem.prototype, "revenueAccountId", 2);
-InvoiceLineItem = __decorateClass$6([
+InvoiceLineItem = __decorateClass$4([
   TenantScoped({ mode: "optional" }),
   smrt({
     api: { include: ["list", "get", "create", "update", "delete"] },
@@ -2702,14 +3225,14 @@ const InvoiceLineItemCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ *
   __proto__: null,
   InvoiceLineItemCollection
 }, Symbol.toStringTag, { value: "Module" }));
-var __defProp$5 = Object.defineProperty;
-var __getOwnPropDesc$5 = Object.getOwnPropertyDescriptor;
-var __decorateClass$5 = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$5(target, key) : target;
+var __defProp$3 = Object.defineProperty;
+var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
+var __decorateClass$3 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$3(target, key) : target;
   for (var i = decorators.length - 1, decorator; i >= 0; i--)
     if (decorator = decorators[i])
       result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp$5(target, key, result);
+  if (kind && result) __defProp$3(target, key, result);
   return result;
 };
 const ALLOCATION_EPSILON = 0.01;
@@ -2746,12 +3269,14 @@ let PaymentAllocation = class extends SmrtObject {
     if (options.notes !== void 0) this.notes = options.notes;
   }
   /**
-   * 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
@@ -2760,6 +3285,16 @@ let PaymentAllocation = class 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.
    */
   async save() {
     if (!Number.isFinite(this.amount) || this.amount <= 0) {
@@ -2791,19 +3326,42 @@ let PaymentAllocation = class extends SmrtObject {
         );
       }
     }
+    if (this.invoiceId) {
+      const { InvoiceCollection: InvoiceCollection2 } = await Promise.resolve().then(() => InvoiceCollection$1);
+      const invoices = await InvoiceCollection2.create(this.options);
+      const invoice = await invoices.get({ id: this.invoiceId });
+      if (invoice && invoice.totalAmount > ALLOCATION_EPSILON) {
+        const { PaymentAllocationCollection: PaymentAllocationCollection2 } = await Promise.resolve().then(() => PaymentAllocationCollection$1);
+        const allocations = await PaymentAllocationCollection2.create(
+          this.options
+        );
+        const existingForInvoice = await allocations.findByInvoice(
+          this.invoiceId
+        );
+        const otherInvoiceTotal = existingForInvoice.reduce(
+          (sum, alloc) => alloc.id === this.id ? sum : sum + alloc.amount,
+          0
+        );
+        if (otherInvoiceTotal + this.amount - invoice.totalAmount > ALLOCATION_EPSILON) {
+          throw new Error(
+            `PaymentAllocation ${this.id ?? "<new>"}: allocating ${this.amount} would over-pay invoice '${this.invoiceId}' — already allocated ${otherInvoiceTotal} of ${invoice.totalAmount}.`
+          );
+        }
+      }
+    }
     return super.save();
   }
 };
-__decorateClass$5([
+__decorateClass$3([
   tenantId({ nullable: true })
 ], PaymentAllocation.prototype, "tenantId", 2);
-__decorateClass$5([
+__decorateClass$3([
   foreignKey("Payment")
 ], PaymentAllocation.prototype, "paymentId", 2);
-__decorateClass$5([
+__decorateClass$3([
   foreignKey("Invoice")
 ], PaymentAllocation.prototype, "invoiceId", 2);
-PaymentAllocation = __decorateClass$5([
+PaymentAllocation = __decorateClass$3([
   TenantScoped({ mode: "optional" }),
   smrt({
     // NOTE: `create` and `delete` are intentionally NOT exposed over the
@@ -2968,14 +3526,14 @@ const PaymentAllocationCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__
   __proto__: null,
   PaymentAllocationCollection
 }, Symbol.toStringTag, { value: "Module" }));
-var __defProp$4 = Object.defineProperty;
-var __getOwnPropDesc$4 = Object.getOwnPropertyDescriptor;
-var __decorateClass$4 = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$4(target, key) : target;
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __decorateClass$2 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(target, key) : target;
   for (var i = decorators.length - 1, decorator; i >= 0; i--)
     if (decorator = decorators[i])
       result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp$4(target, key, result);
+  if (kind && result) __defProp$2(target, key, result);
   return result;
 };
 const PAYMENT_STATUS_TRANSITIONS = {
@@ -3409,19 +3967,19 @@ let Payment = class extends SmrtObject {
     this.status = PaymentStatus.CANCELLED;
   }
 };
-__decorateClass$4([
+__decorateClass$2([
   tenantId({ nullable: true })
 ], Payment.prototype, "tenantId", 2);
-__decorateClass$4([
+__decorateClass$2([
   foreignKey("Contract")
 ], Payment.prototype, "contractId", 2);
-__decorateClass$4([
+__decorateClass$2([
   foreignKey("Customer")
 ], Payment.prototype, "customerId", 2);
-__decorateClass$4([
+__decorateClass$2([
   crossPackageRef("@happyvertical/smrt-ledgers:Journal")
 ], Payment.prototype, "journalId", 2);
-Payment = __decorateClass$4([
+Payment = __decorateClass$2([
   TenantScoped({ mode: "optional" }),
   smrt({
     // ROOT FIX (S5 audit #1390 round 4): restrict the generated create/update
@@ -3629,14 +4187,14 @@ const PaymentCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object
   __proto__: null,
   PaymentCollection
 }, Symbol.toStringTag, { value: "Module" }));
-var __defProp$3 = Object.defineProperty;
-var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
-var __decorateClass$3 = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$3(target, key) : target;
+var __defProp$1 = Object.defineProperty;
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+var __decorateClass$1 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(target, key) : target;
   for (var i = decorators.length - 1, decorator; i >= 0; i--)
     if (decorator = decorators[i])
       result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp$3(target, key, result);
+  if (kind && result) __defProp$1(target, key, result);
   return result;
 };
 const PAYMENT_INTENT_EPSILON = 0.01;
@@ -4333,10 +4891,10 @@ Retired: ${reason}` : `Retired: ${reason}`;
     return null;
   }
 };
-__decorateClass$3([
+__decorateClass$1([
   tenantId({ nullable: true })
 ], PaymentIntent.prototype, "tenantId", 2);
-PaymentIntent = __decorateClass$3([
+PaymentIntent = __decorateClass$1([
   TenantScoped({ mode: "optional" }),
   smrt({
     // Natural-key idempotency: a consumer that retries `create` with the
@@ -4488,14 +5046,14 @@ class PaymentIntentCollection extends SmrtCollection {
     );
   }
 }
-var __defProp$2 = Object.defineProperty;
-var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
-var __decorateClass$2 = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(target, key) : target;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
   for (var i = decorators.length - 1, decorator; i >= 0; i--)
     if (decorator = decorators[i])
       result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp$2(target, key, result);
+  if (kind && result) __defProp(target, key, result);
   return result;
 };
 const PAYOUT_EPSILON = 0.01;
@@ -4863,13 +5421,13 @@ let Payout = class extends SmrtObject {
     return null;
   }
 };
-__decorateClass$2([
+__decorateClass([
   tenantId({ nullable: true })
 ], Payout.prototype, "tenantId", 2);
-__decorateClass$2([
+__decorateClass([
   foreignKey(Vendor)
 ], Payout.prototype, "vendorId", 2);
-Payout = __decorateClass$2([
+Payout = __decorateClass([
   TenantScoped({ mode: "optional" }),
   smrt({
     // ROOT FIX (S5 audit #1390 round 4): a Payout has NO safe generated write.
@@ -5085,178 +5643,6 @@ class VendorCollection extends SmrtCollection {
     );
   }
 }
-var __defProp$1 = Object.defineProperty;
-var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
-var __decorateClass$1 = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(target, key) : target;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp$1(target, key, result);
-  return result;
-};
-let ContractLineItem = class extends SmrtObject {
-  tenantId = null;
-  contractId = "";
-  /**
-   * Item description
-   */
-  description = "";
-  /**
-   * Quantity ordered
-   */
-  quantity = 1;
-  /**
-   * Unit price before discount
-   */
-  unitPrice = 0;
-  /**
-   * Discount amount (flat, not percentage)
-   */
-  discount = 0;
-  /**
-   * Tax rate as decimal (e.g., 0.08 for 8%)
-   */
-  taxRate = 0;
-  /**
-   * Calculated line amount (qty * price - discount + tax)
-   */
-  amount = 0;
-  productId = "";
-  /**
-   * SKU or item code
-   */
-  sku = "";
-  /**
-   * Start date (for lease/subscription items)
-   */
-  startDate = null;
-  /**
-   * End date (for lease/subscription items)
-   */
-  endDate = null;
-  /**
-   * Billing period (for subscriptions: 'monthly', 'yearly', etc.)
-   */
-  billingPeriod = "";
-  /**
-   * Sort order within the contract
-   */
-  sortOrder = 0;
-  constructor(options = {}) {
-    super(options);
-    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
-    if (options.contractId !== void 0) this.contractId = options.contractId;
-    if (options.description !== void 0)
-      this.description = options.description;
-    if (options.quantity !== void 0) this.quantity = options.quantity;
-    if (options.unitPrice !== void 0) this.unitPrice = options.unitPrice;
-    if (options.discount !== void 0) this.discount = options.discount;
-    if (options.taxRate !== void 0) this.taxRate = options.taxRate;
-    if (options.amount !== void 0) this.amount = options.amount;
-    if (options.productId !== void 0) this.productId = options.productId;
-    if (options.sku !== void 0) this.sku = options.sku;
-    if (options.startDate !== void 0) this.startDate = options.startDate;
-    if (options.endDate !== void 0) this.endDate = options.endDate;
-    if (options.billingPeriod !== void 0)
-      this.billingPeriod = options.billingPeriod;
-    if (options.sortOrder !== void 0) this.sortOrder = options.sortOrder;
-  }
-  /**
-   * Calculate the line amount
-   */
-  calculateAmount() {
-    const subtotal = this.quantity * this.unitPrice - this.discount;
-    const tax = subtotal * this.taxRate;
-    return subtotal + tax;
-  }
-  /**
-   * Check if this is a subscription/recurring item
-   */
-  isRecurring() {
-    return !!this.billingPeriod && !!this.startDate;
-  }
-  /**
-   * Check if subscription is active
-   */
-  isSubscriptionActive() {
-    if (!this.isRecurring()) return false;
-    if (!this.startDate) return false;
-    const now = /* @__PURE__ */ new Date();
-    if (now < this.startDate) return false;
-    if (this.endDate && now > this.endDate) return false;
-    return true;
-  }
-};
-__decorateClass$1([
-  tenantId({ nullable: true })
-], ContractLineItem.prototype, "tenantId", 2);
-__decorateClass$1([
-  foreignKey("Contract")
-], ContractLineItem.prototype, "contractId", 2);
-__decorateClass$1([
-  crossPackageRef("@happyvertical/smrt-products:Product")
-], ContractLineItem.prototype, "productId", 2);
-ContractLineItem = __decorateClass$1([
-  TenantScoped({ mode: "optional" }),
-  smrt({
-    tableStrategy: "sti",
-    api: { include: ["list", "get", "create", "update", "delete"] },
-    mcp: { include: ["list", "get"] },
-    cli: true
-  })
-], ContractLineItem);
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __decorateClass = (decorators, target, key, kind) => {
-  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
-  if (kind && result) __defProp(target, key, result);
-  return result;
-};
-let FulfillmentLineItem = class extends SmrtObject {
-  tenantId = null;
-  fulfillmentId = "";
-  contractLineItemId = "";
-  /**
-   * Quantity fulfilled in this fulfillment
-   */
-  quantityFulfilled = 1;
-  /**
-   * Notes about this line item
-   */
-  notes = "";
-  constructor(options = {}) {
-    super(options);
-    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
-    if (options.fulfillmentId !== void 0)
-      this.fulfillmentId = options.fulfillmentId;
-    if (options.contractLineItemId !== void 0)
-      this.contractLineItemId = options.contractLineItemId;
-    if (options.quantityFulfilled !== void 0)
-      this.quantityFulfilled = options.quantityFulfilled;
-    if (options.notes !== void 0) this.notes = options.notes;
-  }
-};
-__decorateClass([
-  tenantId({ nullable: true })
-], FulfillmentLineItem.prototype, "tenantId", 2);
-__decorateClass([
-  foreignKey("Fulfillment")
-], FulfillmentLineItem.prototype, "fulfillmentId", 2);
-__decorateClass([
-  foreignKey("ContractLineItem")
-], FulfillmentLineItem.prototype, "contractLineItemId", 2);
-FulfillmentLineItem = __decorateClass([
-  TenantScoped({ mode: "optional" }),
-  smrt({
-    api: { include: ["list", "get", "create", "update", "delete"] },
-    mcp: { include: ["list", "get"] },
-    cli: true
-  })
-], FulfillmentLineItem);
 export {
   Agreement,
   COMMERCE_MODULE_META,
@@ -5265,6 +5651,7 @@ export {
   Contract,
   ContractCollection,
   ContractLineItem,
+  ContractLineItemCollection,
   ContractStatus,
   ContractType,
   Customer,
@@ -5275,6 +5662,7 @@ export {
   Fulfillment,
   FulfillmentCollection,
   FulfillmentLineItem,
+  FulfillmentLineItemCollection,
   FulfillmentStatus,
   FulfillmentType,
   Invoice,