@open-mercato/core 0.7.1-develop.7120.1.a0154ac412 → 0.7.1-develop.7121.1.734c263bda

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.7.1-develop.7120.1.a0154ac412",
+  "version": "0.7.1-develop.7121.1.734c263bda",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -252,16 +252,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@open-mercato/ai-assistant": "0.7.1-develop.7120.1.a0154ac412",
-    "@open-mercato/shared": "0.7.1-develop.7120.1.a0154ac412",
-    "@open-mercato/ui": "0.7.1-develop.7120.1.a0154ac412",
+    "@open-mercato/ai-assistant": "0.7.1-develop.7121.1.734c263bda",
+    "@open-mercato/shared": "0.7.1-develop.7121.1.734c263bda",
+    "@open-mercato/ui": "0.7.1-develop.7121.1.734c263bda",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/ai-assistant": "0.7.1-develop.7120.1.a0154ac412",
-    "@open-mercato/shared": "0.7.1-develop.7120.1.a0154ac412",
-    "@open-mercato/ui": "0.7.1-develop.7120.1.a0154ac412",
+    "@open-mercato/ai-assistant": "0.7.1-develop.7121.1.734c263bda",
+    "@open-mercato/shared": "0.7.1-develop.7121.1.734c263bda",
+    "@open-mercato/ui": "0.7.1-develop.7121.1.734c263bda",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.1",

package/src/modules/sales/commands/documents.ts

@@ -130,6 +130,11 @@ import {
   type SalesLineCalculationResult,
   type SalesDocumentCalculationResult,
 } from "../lib/types";
+import {
+  mapOrderLineEntityToSnapshot,
+  mapQuoteLineEntityToSnapshot,
+  resolveUpsertDiscountFields,
+} from "../lib/lineSnapshots";
 import { loadShippedQuantityByLine } from "../lib/shipments/snapshots";
 import { resolveDictionaryEntryValue, resolveCachedDictionaryEntryValue } from "../lib/dictionaries";
 import type { CacheStrategy } from "@open-mercato/cache";
@@ -2970,68 +2975,6 @@ function buildCalculationContext(params: {
   };
 }
 
-function mapOrderLineEntityToSnapshot(line: SalesOrderLine): SalesLineSnapshot {
-  return {
-    id: line.id,
-    lineNumber: line.lineNumber,
-    kind: line.kind,
-    productId: line.productId ?? null,
-    productVariantId: line.productVariantId ?? null,
-    name: line.name ?? null,
-    description: line.description ?? null,
-    comment: line.comment ?? null,
-    quantity: toNumeric(line.quantity),
-    quantityUnit: line.quantityUnit ?? null,
-    normalizedQuantity: toNumeric(line.normalizedQuantity ?? line.quantity),
-    normalizedUnit: line.normalizedUnit ?? line.quantityUnit ?? null,
-    uomSnapshot: line.uomSnapshot ? cloneJson(line.uomSnapshot) : null,
-    currencyCode: line.currencyCode,
-    unitPriceNet: toNumeric(line.unitPriceNet),
-    unitPriceGross: toNumeric(line.unitPriceGross),
-    discountAmount: toNumeric(line.discountAmount),
-    discountPercent: toNumeric(line.discountPercent),
-    taxRate: toNumeric(line.taxRate),
-    taxAmount: toNumeric(line.taxAmount),
-    totalNetAmount: toNumeric(line.totalNetAmount),
-    totalGrossAmount: toNumeric(line.totalGrossAmount),
-    configuration: line.configuration ? cloneJson(line.configuration) : null,
-    promotionCode: line.promotionCode ?? null,
-    metadata: line.metadata ? cloneJson(line.metadata) : null,
-    customFieldSetId: line.customFieldSetId ?? null,
-  };
-}
-
-function mapQuoteLineEntityToSnapshot(line: SalesQuoteLine): SalesLineSnapshot {
-  return {
-    id: line.id,
-    lineNumber: line.lineNumber,
-    kind: line.kind,
-    productId: line.productId ?? null,
-    productVariantId: line.productVariantId ?? null,
-    name: line.name ?? null,
-    description: line.description ?? null,
-    comment: line.comment ?? null,
-    quantity: toNumeric(line.quantity),
-    quantityUnit: line.quantityUnit ?? null,
-    normalizedQuantity: toNumeric(line.normalizedQuantity ?? line.quantity),
-    normalizedUnit: line.normalizedUnit ?? line.quantityUnit ?? null,
-    uomSnapshot: line.uomSnapshot ? cloneJson(line.uomSnapshot) : null,
-    currencyCode: line.currencyCode,
-    unitPriceNet: toNumeric(line.unitPriceNet),
-    unitPriceGross: toNumeric(line.unitPriceGross),
-    discountAmount: toNumeric(line.discountAmount),
-    discountPercent: toNumeric(line.discountPercent),
-    taxRate: toNumeric(line.taxRate),
-    taxAmount: toNumeric(line.taxAmount),
-    totalNetAmount: toNumeric(line.totalNetAmount),
-    totalGrossAmount: toNumeric(line.totalGrossAmount),
-    configuration: line.configuration ? cloneJson(line.configuration) : null,
-    promotionCode: line.promotionCode ?? null,
-    metadata: line.metadata ? cloneJson(line.metadata) : null,
-    customFieldSetId: line.customFieldSetId ?? null,
-  };
-}
-
 function mapOrderAdjustmentToDraft(
   adjustment: SalesOrderAdjustment,
 ): SalesAdjustmentDraft {
@@ -3088,6 +3031,13 @@ async function emitTotalsCalculated(
   await eventBus.emitEvent("sales.document.totals.calculated", payload);
 }
 
+function isStoredRowSourcedLine(line: DocumentLineCreateInput): boolean {
+  return (
+    (line as Pick<SalesLineSnapshot, "discountAmountFromStoredRow">)
+      .discountAmountFromStoredRow === true
+  );
+}
+
 function createLineSnapshotFromInput(
   line: DocumentLineCreateInput,
   lineNumber: number,
@@ -3119,6 +3069,16 @@ function createLineSnapshotFromInput(
     unitPriceNet: line.unitPriceNet ?? null,
     unitPriceGross: line.unitPriceGross ?? null,
     discountAmount: line.discountAmount ?? null,
+    // Several callers re-run an already-mapped snapshot through here — the line
+    // upsert and delete paths rebuild every line of the document, not just the
+    // one being edited. Those inputs already carry a line total from a stored
+    // row, so their origin must survive rather than be overwritten with the
+    // caller default, or the untouched lines get re-inflated by quantity on
+    // every write. Exactly one of the two origin fields is ever set, which is
+    // the invariant the calculation engine relies on.
+    ...(isStoredRowSourcedLine(line)
+      ? { discountAmountFromStoredRow: true }
+      : { discountAmountBasis: line.discountAmountBasis ?? "unit" }),
     discountPercent: line.discountPercent ?? null,
     taxRate: line.taxRate ?? null,
     taxAmount: line.taxAmount ?? null,
@@ -7267,8 +7227,11 @@ const orderLineUpsertCommand: CommandHandler<
         order.currencyCode,
       unitPriceNet: unitPriceNet ?? 0,
       unitPriceGross: unitPriceGross ?? unitPriceNet ?? 0,
-      discountAmount:
-        parsed.discountAmount ?? existingSnapshot?.discountAmount ?? 0,
+      ...resolveUpsertDiscountFields(
+        parsed.discountAmount,
+        parsed.discountAmountBasis,
+        existingSnapshot,
+      ),
       discountPercent:
         parsed.discountPercent ?? existingSnapshot?.discountPercent ?? 0,
       taxRate: taxRate ?? 0,
@@ -7761,8 +7724,11 @@ const quoteLineUpsertCommand: CommandHandler<
         quote.currencyCode,
       unitPriceNet: unitPriceNet ?? 0,
       unitPriceGross: unitPriceGross ?? unitPriceNet ?? 0,
-      discountAmount:
-        parsed.discountAmount ?? existingSnapshot?.discountAmount ?? 0,
+      ...resolveUpsertDiscountFields(
+        parsed.discountAmount,
+        parsed.discountAmountBasis,
+        existingSnapshot,
+      ),
       discountPercent:
         parsed.discountPercent ?? existingSnapshot?.discountPercent ?? 0,
       taxRate: taxRate ?? 0,

package/src/modules/sales/commands/returns.ts

@@ -16,6 +16,7 @@ import type { SalesAdjustmentDraft, SalesLineSnapshot, SalesDocumentCalculationR
 import { cloneJson, deriveLineNetFromGross, ensureOrganizationScope, ensureSameScope, ensureTenantScope, extractUndoPayload, toNumericString, enforceSalesDocumentOptimisticLock, SALES_RESOURCE_KIND_ORDER, SALES_RESOURCE_KIND_RETURN } from './shared'
 import { resolveRedoSnapshot } from '@open-mercato/shared/lib/commands/redo'
 import { SalesOrder, SalesOrderAdjustment, SalesOrderLine, SalesReturn, SalesReturnLine } from '../data/entities'
+import { mapOrderLineEntityToSnapshot } from '../lib/lineSnapshots'
 import { loadShippedQuantityByLine } from '../lib/shipments/snapshots'
 import { computeAvailableReturnQuantity } from '../lib/returnQuantity'
 import {
@@ -134,37 +135,6 @@ function applyOrderTotals(order: SalesOrder, totals: SalesDocumentCalculationRes
   order.lineItemCount = lineCount
 }
 
-function mapOrderLineEntityToSnapshot(line: SalesOrderLine): SalesLineSnapshot {
-  return {
-    id: line.id,
-    lineNumber: line.lineNumber,
-    kind: line.kind,
-    productId: line.productId ?? null,
-    productVariantId: line.productVariantId ?? null,
-    name: line.name ?? null,
-    description: line.description ?? null,
-    comment: line.comment ?? null,
-    quantity: toNumeric(line.quantity),
-    quantityUnit: line.quantityUnit ?? null,
-    normalizedQuantity: toNumeric(line.normalizedQuantity ?? line.quantity),
-    normalizedUnit: line.normalizedUnit ?? line.quantityUnit ?? null,
-    uomSnapshot: line.uomSnapshot ? cloneJson(line.uomSnapshot) : null,
-    currencyCode: line.currencyCode,
-    unitPriceNet: toNumeric(line.unitPriceNet),
-    unitPriceGross: toNumeric(line.unitPriceGross),
-    discountAmount: toNumeric(line.discountAmount),
-    discountPercent: toNumeric(line.discountPercent),
-    taxRate: toNumeric(line.taxRate),
-    taxAmount: toNumeric(line.taxAmount),
-    totalNetAmount: toNumeric(line.totalNetAmount),
-    totalGrossAmount: toNumeric(line.totalGrossAmount),
-    configuration: line.configuration ? cloneJson(line.configuration) : null,
-    promotionCode: line.promotionCode ?? null,
-    metadata: line.metadata ? cloneJson(line.metadata) : null,
-    customFieldSetId: line.customFieldSetId ?? null,
-  }
-}
-
 function mapOrderAdjustmentToDraft(adjustment: SalesOrderAdjustment): SalesAdjustmentDraft {
   return {
     id: adjustment.id,

package/src/modules/sales/commands/shared.ts

@@ -49,10 +49,7 @@ export async function enforceSalesDocumentOptimisticLock(
   })
 }
 
-export function cloneJson<T>(value: T): T {
-  if (value === null || value === undefined) return value
-  return JSON.parse(JSON.stringify(value)) as T
-}
+export { cloneJson } from '../lib/json'
 
 export function toNumericString(value: number | null | undefined): string | null {
   if (value === undefined || value === null) return null

package/src/modules/sales/components/documents/SalesOrderDraftLines.tsx

@@ -49,6 +49,17 @@ export function createSalesOrderLineDraft(
   const catalogSnapshot = payload.catalogSnapshot && typeof payload.catalogSnapshot === 'object'
     ? payload.catalogSnapshot as Record<string, unknown>
     : null
+  // `payload` is forwarded verbatim to the create API, where a supplied
+  // `discountAmount` is read per unit unless the caller says otherwise, while
+  // `record` below drives the grid, which shows the discount for the whole
+  // line. The multiplication is therefore the conversion between the two, not a
+  // second copy of the per-unit misreading the calculation engine used to hold
+  // — but it has to stop when the caller has explicitly said the amount is
+  // already a line total, or the grid would show the discount quantity times
+  // over while the persisted order shows it once.
+  const draftDiscountAmount = payload.discountAmountBasis === 'line'
+    ? normalizeNumber(payload.discountAmount, 0)
+    : normalizeNumber(payload.discountAmount, 0) * quantity
 
   return {
     id,
@@ -65,7 +76,7 @@ export function createSalesOrderLineDraft(
       currencyCode: typeof payload.currencyCode === 'string' ? payload.currencyCode : null,
       unitPriceNet,
       unitPriceGross,
-      discountAmount: normalizeNumber(payload.discountAmount, 0) * quantity,
+      discountAmount: draftDiscountAmount,
       discountPercent: normalizeNumber(payload.discountPercent, 0),
       taxRate,
       totalNet,

package/src/modules/sales/data/validators.ts

@@ -340,6 +340,9 @@ const linePricingSchema = z.object({
   priceMode: z.enum(['net', 'gross']).optional(),
   taxRateId: uuid().optional(),
   discountAmount: decimal({ min: 0 }).optional(),
+  // How to read a supplied `discountAmount`. Omitting it reproduces the meaning
+  // the API has always documented — per unit — so no existing caller changes.
+  discountAmountBasis: z.enum(['unit', 'line']).optional(),
   discountPercent: percentage().optional(),
   taxRate: percentage().optional(),
   taxAmount: decimal({ min: 0 }).optional(),

package/src/modules/sales/lib/calculations.ts

@@ -77,6 +77,35 @@ function resolveAdjustmentAmounts(
   })
 }
 
+// `discount_amount` stores the discount for the WHOLE line, while
+// `discount_percent` records the operator's intent. The percentage therefore
+// wins whenever it is set: a stored amount is only ever its cached result, and
+// because the column is NOT NULL DEFAULT '0' a stored 0 cannot be told apart
+// from "no discount supplied" — so it counts as absent rather than as a
+// suppressing value. That is what makes recalculation idempotent, and what lets
+// a row whose amount the old engine dropped or re-inflated heal itself on the
+// next pass. Spec: .ai/specs/2026-08-07-sales-line-discount-amount-contract.md.
+function resolveLineDiscountTotal(
+  line: SalesLineSnapshot,
+  netSubtotalBeforeDiscount: number,
+  quantity: number,
+): number {
+  const percent = toNumber(line.discountPercent, 0)
+  if (line.discountPercent !== null && line.discountPercent !== undefined && percent !== 0) {
+    return (percent / 100) * netSubtotalBeforeDiscount
+  }
+
+  const amount = toNumber(line.discountAmount, 0)
+  if (line.discountAmount === null || line.discountAmount === undefined || amount === 0) return 0
+
+  // A snapshot rebuilt from a persisted row already holds a line total, so it
+  // is never multiplied out again. Anything else came from a caller and keeps
+  // the per-unit meaning the API has always documented unless the caller says
+  // otherwise.
+  if (line.discountAmountFromStoredRow === true) return amount
+  return line.discountAmountBasis === 'line' ? amount : amount * quantity
+}
+
 function buildBaseLineResult(line: SalesLineSnapshot): SalesLineCalculationResult {
   const quantity = Math.max(toNumber(line.quantity, 0), 0)
   const taxRate = toNumber(line.taxRate, 0) / 100
@@ -85,14 +114,11 @@ function buildBaseLineResult(line: SalesLineSnapshot): SalesLineCalculationResul
     (line.unitPriceGross !== null && line.unitPriceGross !== undefined
       ? toNumber(line.unitPriceGross) / (1 + taxRate)
       : 0)
-  const discountPerUnit =
-    line.discountAmount ??
-    (line.discountPercent !== null && line.discountPercent !== undefined
-      ? toNumber(line.discountPercent, 0) / 100 * toNumber(unitNet, 0)
-      : 0)
-
   const netSubtotalBeforeDiscount = toNumber(unitNet, 0) * quantity
-  const discountTotal = Math.min(Math.max(discountPerUnit * quantity, 0), netSubtotalBeforeDiscount)
+  const discountTotal = Math.min(
+    Math.max(resolveLineDiscountTotal(line, netSubtotalBeforeDiscount, quantity), 0),
+    netSubtotalBeforeDiscount,
+  )
   const netSubtotal = Math.max(netSubtotalBeforeDiscount - discountTotal, 0)
   const explicitTaxAmount = line.taxAmount !== null && line.taxAmount !== undefined
   let taxAmount = explicitTaxAmount

package/src/modules/sales/lib/json.ts

@@ -0,0 +1,4 @@
+export function cloneJson<T>(value: T): T {
+  if (value === null || value === undefined) return value
+  return JSON.parse(JSON.stringify(value)) as T
+}

package/src/modules/sales/lib/lineSnapshots.ts

@@ -0,0 +1,98 @@
+import type { SalesOrderLine, SalesQuoteLine } from '../data/entities'
+import { cloneJson } from './json'
+import type { SalesLineDiscountBasis, SalesLineSnapshot } from './types'
+
+function toNumeric(value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && value.trim().length) {
+    const parsed = Number(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return 0
+}
+
+function mapPersistedLine(line: SalesOrderLine | SalesQuoteLine): SalesLineSnapshot {
+  return {
+    id: line.id,
+    lineNumber: line.lineNumber,
+    kind: line.kind,
+    productId: line.productId ?? null,
+    productVariantId: line.productVariantId ?? null,
+    name: line.name ?? null,
+    description: line.description ?? null,
+    comment: line.comment ?? null,
+    quantity: toNumeric(line.quantity),
+    quantityUnit: line.quantityUnit ?? null,
+    normalizedQuantity: toNumeric(line.normalizedQuantity ?? line.quantity),
+    normalizedUnit: line.normalizedUnit ?? line.quantityUnit ?? null,
+    uomSnapshot: line.uomSnapshot ? cloneJson(line.uomSnapshot) : null,
+    currencyCode: line.currencyCode,
+    unitPriceNet: toNumeric(line.unitPriceNet),
+    unitPriceGross: toNumeric(line.unitPriceGross),
+    discountAmount: toNumeric(line.discountAmount),
+    // The persisted column holds the discount for the whole line, so the
+    // calculation engine must not multiply it out by quantity again. This flag
+    // is the only thing standing between a round trip and a compounding
+    // re-inflation, and it is why mappers must never set `discountAmountBasis`
+    // instead — that one means "a caller asserted this".
+    discountAmountFromStoredRow: true,
+    discountPercent: toNumeric(line.discountPercent),
+    taxRate: toNumeric(line.taxRate),
+    taxAmount: toNumeric(line.taxAmount),
+    totalNetAmount: toNumeric(line.totalNetAmount),
+    totalGrossAmount: toNumeric(line.totalGrossAmount),
+    configuration: line.configuration ? cloneJson(line.configuration) : null,
+    promotionCode: line.promotionCode ?? null,
+    metadata: line.metadata ? cloneJson(line.metadata) : null,
+    customFieldSetId: line.customFieldSetId ?? null,
+  }
+}
+
+/**
+ * Rebuild a calculation snapshot from a persisted order line.
+ *
+ * Shared by `commands/documents.ts` and `commands/returns.ts` on purpose: the
+ * two files used to carry byte-identical copies, and that duplication is why
+ * the return flows kept the discount defect after the order flows were fixed.
+ */
+export function mapOrderLineEntityToSnapshot(line: SalesOrderLine): SalesLineSnapshot {
+  return mapPersistedLine(line)
+}
+
+export function mapQuoteLineEntityToSnapshot(line: SalesQuoteLine): SalesLineSnapshot {
+  return mapPersistedLine(line)
+}
+
+type UpsertDiscountFields = Pick<
+  SalesLineSnapshot,
+  'discountAmount' | 'discountAmountBasis' | 'discountAmountFromStoredRow'
+>
+
+/**
+ * Decide the discount fields of an upsert payload one operand at a time.
+ *
+ * A line upsert can source its amount from two places with opposite meanings: a
+ * caller value, which is per unit unless the caller says otherwise, and the
+ * stored row, which is always a line total. Collapsing them into a single
+ * `caller ?? stored` expression means whichever origin the merged result is
+ * tagged with is wrong half the time — and the half that breaks is the
+ * upsert-existing path, which then re-inflates by a further factor of quantity
+ * while looking perfectly correct.
+ *
+ * Keeping `null` rather than `0` for "nothing supplied" is deliberate too: the
+ * column cannot represent that distinction, but the payload can, and the
+ * calculation engine needs it to tell a suppressing zero from an absent value.
+ */
+export function resolveUpsertDiscountFields(
+  callerAmount: number | null | undefined,
+  callerBasis: SalesLineDiscountBasis | null | undefined,
+  existingSnapshot: Pick<SalesLineSnapshot, 'discountAmount'> | null | undefined,
+): UpsertDiscountFields {
+  if (callerAmount !== null && callerAmount !== undefined) {
+    return { discountAmount: callerAmount, discountAmountBasis: callerBasis ?? 'unit' }
+  }
+  return {
+    discountAmount: existingSnapshot?.discountAmount ?? null,
+    discountAmountFromStoredRow: existingSnapshot != null,
+  }
+}

package/src/modules/sales/lib/types.ts

@@ -32,6 +32,13 @@ export type SalesLineUomSnapshot = {
   }
 }
 
+/**
+ * How a caller-supplied `discountAmount` should be read: as a rate per unit, or
+ * as the total for the whole line. Persisted rows always hold a line total —
+ * see `discountAmountFromStoredRow`, which is a separate signal on purpose.
+ */
+export type SalesLineDiscountBasis = 'unit' | 'line'
+
 export type SalesLineSnapshot = {
   id?: string
   lineNumber?: number
@@ -50,6 +57,19 @@ export type SalesLineSnapshot = {
   unitPriceNet?: number | null
   unitPriceGross?: number | null
   discountAmount?: number | null
+  /**
+   * Caller-supplied ONLY. How to interpret a supplied `discountAmount`.
+   * Omitted means 'unit', which is the meaning the API has always documented.
+   * Entity-to-snapshot mappers MUST NOT set this: a populated value is what
+   * makes this a reliable *caller* signal.
+   */
+  discountAmountBasis?: SalesLineDiscountBasis | null
+  /**
+   * Set by entity-to-snapshot mappers ONLY. Marks `discountAmount` as
+   * reconstructed from a persisted row, so it is a line total and is NOT a
+   * caller assertion. Never persisted; never accepted from a request.
+   */
+  discountAmountFromStoredRow?: boolean
   discountPercent?: number | null
   taxRate?: number | null
   taxAmount?: number | null