@open-mercato/core 0.7.1-develop.7113.1.9d83dca10c → 0.7.1-develop.7121.1.734c263bda

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

@@ -1,6 +1,7 @@
 // @ts-nocheck
 
 import { randomUUID } from "crypto";
+import { isDeepStrictEqual } from "node:util";
 import { z } from "zod";
 import { registerCommand } from "@open-mercato/shared/lib/commands";
 import type { CommandHandler } from "@open-mercato/shared/lib/commands";
@@ -129,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";
@@ -2969,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 {
@@ -3087,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,
@@ -3118,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,
@@ -7266,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,
@@ -7760,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,
@@ -9197,6 +9164,88 @@ const createInvoiceCommand: CommandHandler<
   },
 };
 
+const invoiceUpdateChangeKeys = [
+  "invoiceNumber",
+  "statusEntryId",
+  "status",
+  "issueDate",
+  "dueDate",
+  "currencyCode",
+  "subtotalNetAmount",
+  "subtotalGrossAmount",
+  "discountTotalAmount",
+  "taxTotalAmount",
+  "grandTotalNetAmount",
+  "grandTotalGrossAmount",
+  "paidTotalAmount",
+  "outstandingAmount",
+  "metadata",
+] as const;
+
+function toAuditISOString(value: unknown): string | null {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  }
+  if (typeof value === "string") {
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+  }
+  return null;
+}
+
+function auditValuesEqual(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+  if (left instanceof Date || right instanceof Date) {
+    const leftIso = toAuditISOString(left);
+    const rightIso = toAuditISOString(right);
+    return leftIso !== null && rightIso !== null && leftIso === rightIso;
+  }
+  return isDeepStrictEqual(left, right);
+}
+
+function buildAuditChanges(
+  before: Record<string, unknown>,
+  after: Record<string, unknown>,
+  keys: readonly string[],
+): Record<string, { from: unknown; to: unknown }> {
+  const changedKeys = keys.filter((key) => !auditValuesEqual(before[key], after[key]));
+  return buildChanges(before, after, changedKeys);
+}
+
+function selectInvoiceUpdateChangeKeys(
+  input: z.infer<typeof invoiceUpdateSchema>,
+): Array<(typeof invoiceUpdateChangeKeys)[number]> {
+  return invoiceUpdateChangeKeys.filter((key) =>
+    key === "status"
+      ? input.statusEntryId !== undefined
+      : input[key as keyof z.infer<typeof invoiceUpdateSchema>] !== undefined,
+  );
+}
+
+function applyInvoiceHeaderUpdate(
+  invoice: SalesInvoice,
+  input: z.infer<typeof invoiceUpdateSchema>,
+  resolvedStatus: string | null | undefined,
+): void {
+  if (input.invoiceNumber !== undefined) invoice.invoiceNumber = input.invoiceNumber;
+  if (input.statusEntryId !== undefined) {
+    invoice.statusEntryId = input.statusEntryId;
+    invoice.status = resolvedStatus ?? null;
+  }
+  if (input.issueDate !== undefined) invoice.issueDate = input.issueDate;
+  if (input.dueDate !== undefined) invoice.dueDate = input.dueDate;
+  if (input.currencyCode !== undefined) invoice.currencyCode = input.currencyCode;
+  if (input.subtotalNetAmount !== undefined) invoice.subtotalNetAmount = toNumericString(input.subtotalNetAmount);
+  if (input.subtotalGrossAmount !== undefined) invoice.subtotalGrossAmount = toNumericString(input.subtotalGrossAmount);
+  if (input.discountTotalAmount !== undefined) invoice.discountTotalAmount = toNumericString(input.discountTotalAmount);
+  if (input.taxTotalAmount !== undefined) invoice.taxTotalAmount = toNumericString(input.taxTotalAmount);
+  if (input.grandTotalNetAmount !== undefined) invoice.grandTotalNetAmount = toNumericString(input.grandTotalNetAmount);
+  if (input.grandTotalGrossAmount !== undefined) invoice.grandTotalGrossAmount = toNumericString(input.grandTotalGrossAmount);
+  if (input.paidTotalAmount !== undefined) invoice.paidTotalAmount = toNumericString(input.paidTotalAmount);
+  if (input.outstandingAmount !== undefined) invoice.outstandingAmount = toNumericString(input.outstandingAmount);
+  if (input.metadata !== undefined) invoice.metadata = input.metadata;
+}
+
 const updateInvoiceCommand: CommandHandler<
   z.infer<typeof invoiceUpdateSchema>,
   { invoiceId: string }
@@ -9225,29 +9274,12 @@ const updateInvoiceCommand: CommandHandler<
       deletedAt: null,
     });
 
-    const changes = buildChanges(invoice, parsed, [
-      "invoiceNumber",
-      "statusEntryId",
-      "status",
-      "issueDate",
-      "dueDate",
-      "currencyCode",
-      "subtotalNetAmount",
-      "subtotalGrossAmount",
-      "discountTotalAmount",
-      "taxTotalAmount",
-      "grandTotalNetAmount",
-      "grandTotalGrossAmount",
-      "paidTotalAmount",
-      "outstandingAmount",
-      "metadata",
-    ]);
-
+    let resolvedStatus: string | null | undefined;
     if (parsed.statusEntryId !== undefined) {
-      invoice.status = await resolveDictionaryEntryValue(em, parsed.statusEntryId ?? null, { tenantId: invoice.tenantId });
+      resolvedStatus = await resolveDictionaryEntryValue(em, parsed.statusEntryId ?? null, { tenantId: invoice.tenantId });
     }
 
-    Object.assign(invoice, changes);
+    applyInvoiceHeaderUpdate(invoice, parsed, resolvedStatus);
     invoice.updatedAt = new Date();
     await em.flush();
 
@@ -9283,11 +9315,18 @@ const updateInvoiceCommand: CommandHandler<
     const em = (ctx.container.resolve("em") as EntityManager).fork();
     return loadInvoiceSnapshot(em, result.invoiceId);
   },
-  buildLog: async ({ result, snapshots }) => {
+  buildLog: async ({ input, result, snapshots }) => {
     const before = snapshots.before as InvoiceGraphSnapshot | undefined;
     const after = snapshots.after as InvoiceGraphSnapshot | undefined;
     if (!after) return null;
     const { translate } = await resolveTranslations();
+    const changes = before
+      ? buildAuditChanges(
+          before.invoice as unknown as Record<string, unknown>,
+          after.invoice as unknown as Record<string, unknown>,
+          selectInvoiceUpdateChangeKeys(input),
+        )
+      : {};
     return {
       actionLabel: translate("sales.audit.invoices.update", "Update invoice"),
       resourceKind: "sales.invoice",
@@ -9296,6 +9335,7 @@ const updateInvoiceCommand: CommandHandler<
       organizationId: after.invoice.organizationId,
       snapshotBefore: before,
       snapshotAfter: after,
+      changes: Object.keys(changes).length ? changes : null,
       payload: {
         undo: { before, after } satisfies InvoiceUndoPayload,
       },
@@ -9704,6 +9744,52 @@ const createCreditMemoCommand: CommandHandler<
   },
 };
 
+const creditMemoUpdateChangeKeys = [
+  "creditMemoNumber",
+  "statusEntryId",
+  "status",
+  "reason",
+  "issueDate",
+  "currencyCode",
+  "subtotalNetAmount",
+  "subtotalGrossAmount",
+  "taxTotalAmount",
+  "grandTotalNetAmount",
+  "grandTotalGrossAmount",
+  "metadata",
+] as const;
+
+function selectCreditMemoUpdateChangeKeys(
+  input: z.infer<typeof creditMemoUpdateSchema>,
+): Array<(typeof creditMemoUpdateChangeKeys)[number]> {
+  return creditMemoUpdateChangeKeys.filter((key) =>
+    key === "status"
+      ? input.statusEntryId !== undefined
+      : input[key as keyof z.infer<typeof creditMemoUpdateSchema>] !== undefined,
+  );
+}
+
+function applyCreditMemoHeaderUpdate(
+  creditMemo: SalesCreditMemo,
+  input: z.infer<typeof creditMemoUpdateSchema>,
+  resolvedStatus: string | null | undefined,
+): void {
+  if (input.creditMemoNumber !== undefined) creditMemo.creditMemoNumber = input.creditMemoNumber;
+  if (input.statusEntryId !== undefined) {
+    creditMemo.statusEntryId = input.statusEntryId;
+    creditMemo.status = resolvedStatus ?? null;
+  }
+  if (input.reason !== undefined) creditMemo.reason = input.reason;
+  if (input.issueDate !== undefined) creditMemo.issueDate = input.issueDate;
+  if (input.currencyCode !== undefined) creditMemo.currencyCode = input.currencyCode;
+  if (input.subtotalNetAmount !== undefined) creditMemo.subtotalNetAmount = toNumericString(input.subtotalNetAmount);
+  if (input.subtotalGrossAmount !== undefined) creditMemo.subtotalGrossAmount = toNumericString(input.subtotalGrossAmount);
+  if (input.taxTotalAmount !== undefined) creditMemo.taxTotalAmount = toNumericString(input.taxTotalAmount);
+  if (input.grandTotalNetAmount !== undefined) creditMemo.grandTotalNetAmount = toNumericString(input.grandTotalNetAmount);
+  if (input.grandTotalGrossAmount !== undefined) creditMemo.grandTotalGrossAmount = toNumericString(input.grandTotalGrossAmount);
+  if (input.metadata !== undefined) creditMemo.metadata = input.metadata;
+}
+
 const updateCreditMemoCommand: CommandHandler<
   z.infer<typeof creditMemoUpdateSchema>,
   { creditMemoId: string }
@@ -9732,26 +9818,12 @@ const updateCreditMemoCommand: CommandHandler<
       deletedAt: null,
     });
 
-    const changes = buildChanges(creditMemo, parsed, [
-      "creditMemoNumber",
-      "statusEntryId",
-      "status",
-      "reason",
-      "issueDate",
-      "currencyCode",
-      "subtotalNetAmount",
-      "subtotalGrossAmount",
-      "taxTotalAmount",
-      "grandTotalNetAmount",
-      "grandTotalGrossAmount",
-      "metadata",
-    ]);
-
+    let resolvedStatus: string | null | undefined;
     if (parsed.statusEntryId !== undefined) {
-      creditMemo.status = await resolveDictionaryEntryValue(em, parsed.statusEntryId ?? null, { tenantId: creditMemo.tenantId });
+      resolvedStatus = await resolveDictionaryEntryValue(em, parsed.statusEntryId ?? null, { tenantId: creditMemo.tenantId });
     }
 
-    Object.assign(creditMemo, changes);
+    applyCreditMemoHeaderUpdate(creditMemo, parsed, resolvedStatus);
     creditMemo.updatedAt = new Date();
     await em.flush();
 
@@ -9787,11 +9859,18 @@ const updateCreditMemoCommand: CommandHandler<
     const em = (ctx.container.resolve("em") as EntityManager).fork();
     return loadCreditMemoSnapshot(em, result.creditMemoId);
   },
-  buildLog: async ({ result, snapshots }) => {
+  buildLog: async ({ input, result, snapshots }) => {
     const before = snapshots.before as CreditMemoGraphSnapshot | undefined;
     const after = snapshots.after as CreditMemoGraphSnapshot | undefined;
     if (!after) return null;
     const { translate } = await resolveTranslations();
+    const changes = before
+      ? buildAuditChanges(
+          before.creditMemo as unknown as Record<string, unknown>,
+          after.creditMemo as unknown as Record<string, unknown>,
+          selectCreditMemoUpdateChangeKeys(input),
+        )
+      : {};
     return {
       actionLabel: translate("sales.audit.credit_memos.update", "Update credit memo"),
       resourceKind: "sales.credit_memo",
@@ -9800,6 +9879,7 @@ const updateCreditMemoCommand: CommandHandler<
       organizationId: after.creditMemo.organizationId,
       snapshotBefore: before,
       snapshotAfter: after,
+      changes: Object.keys(changes).length ? changes : null,
       payload: {
         undo: { before, after } satisfies CreditMemoUndoPayload,
       },

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,
+  }
+}