@dainamite/cpq 0.4.0 → 0.6.0

package/src/modules/cpq/services/cpqQuotingService.ts

@@ -1,3 +1,12 @@
+import { cloneQuoteAdjustments, removeQuoteLineTree } from './priceAdjustments/quoteAdjustmentLifecycle'
+import type { PriceAdjustment } from '../data/price-adjustments'
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import { loadQuoteAdjustments } from './priceAdjustments/loadQuoteAdjustments'
+import { resolveManualAdjustments } from './priceAdjustments/resolveManualAdjustments'
+import { withChargeWaterfall } from './priceAdjustments/chargeWaterfall'
+import { withQuotePricingWrite } from './priceAdjustments/quotePricingWrite'
+import { emitQuoteWriteEvents, type QuoteWriteEvents } from './priceAdjustments/quotePricingEvents'
+import { computeWaterfallSummary } from './priceAdjustments/pricingSnapshot'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { SalesQuote, SalesQuoteLine } from '@open-mercato/core/modules/sales/data/entities'
 import { CustomerEntity } from '@open-mercato/core/modules/customers/data/entities'
@@ -36,6 +45,17 @@ import {
   ARC_QUOTE_TYPES,
   getBaseCurrencyCode,
 } from './types'
+import {
+  ARC_PRICE_FROZEN_KEY,
+  ARC_REPRICED_KEY,
+  arcPricingInputsChanged,
+  buildArcMirrorConfiguration,
+  isFrozenAmendMirrorLine,
+  isArcMirrorLine,
+  stripArcMarkers,
+  stripQuoteOnlyArcMarkers,
+} from './arcPriceFreeze'
+import { isArcCancelledLine, planArcLineRemoval, planArcLineRestore, removalCancelsItem } from './arcLineRemoval'
 
 interface QuotingServiceDeps {
   em: EntityManager
@@ -169,15 +189,32 @@ export class DefaultCpqQuotingService {
   // ─── Add Quote Item ────────────────────────────────────────────
 
   async addQuoteItem(quoteId: string, item: QuoteItemInput, scope: TenantScope): Promise<QuoteResult> {
-    const em = this.em
+    return this.writeQuote(quoteId, scope, (em, quote) => this.addQuoteItemInTransaction(quoteId, item, scope, em, quote), undefined, undefined, LINE_EVENTS)
+  }
+
+  private async addQuoteItemInTransaction(quoteId: string, item: QuoteItemInput, scope: TenantScope, em: EntityManager, cpqConfig: CpqQuoteConfiguration): Promise<QuoteResult> {
+    // ARC markers (`_arc*`) are server-owned — never accept them from callers.
+    item = { ...item, configuration: stripArcMarkers(item.configuration) }
 
-    const cpqConfig = await this.loadCpqConfig(em, quoteId, scope)
     const salesQuote = await this.loadSalesQuote(em, cpqConfig.quoteId, scope)
 
     if (TERMINAL_STATUSES.includes(cpqConfig.cpqStatus as CpqStatus)) {
       throw new QuotingError(409, `Cannot modify quote in '${cpqConfig.cpqStatus}' status`)
     }
 
+    if (item.parentLineId && cpqConfig.quoteType && cpqConfig.quoteType !== 'new') {
+      const parent = await em.findOne(CpqQuoteLineConfiguration, {
+        quoteLineId: item.parentLineId,
+        quoteConfigurationId: cpqConfig.id,
+        organizationId: scope.organizationId,
+        tenantId: scope.tenantId,
+        deletedAt: null,
+      })
+      if (parent && isArcCancelledLine(parent, cpqConfig.quoteType)) {
+        throw new QuotingError(409, 'Cannot add a component to a subscription item marked for removal')
+      }
+    }
+
     // Resolve offering -> spec -> product
     const { offering, spec } = await this.resolveOffering(em, item, scope)
 
@@ -322,15 +359,23 @@ export class DefaultCpqQuotingService {
 
   // ─── Update Quote Item ─────────────────────────────────────────
 
-  async updateQuoteItem(
+  async updateQuoteItem(quoteId: string,
+    lineId: string,
+    update: { configuration: Record<string, unknown>; quantity?: number; usageEstimates?: Array<{ chargeCode: string; estimatedQuantity: number }>; startDate?: string; termMonths?: number; endDate?: string },
+    scope: TenantScope): Promise<QuoteResult> {
+    return this.writeQuote(quoteId, scope, (em, quote) => this.updateQuoteItemInTransaction(quoteId, lineId, update, scope, em, quote), undefined, undefined, LINE_EVENTS)
+  }
+
+  private async updateQuoteItemInTransaction(
     quoteId: string,
     lineId: string,
     update: { configuration: Record<string, unknown>; quantity?: number; usageEstimates?: Array<{ chargeCode: string; estimatedQuantity: number }>; startDate?: string; termMonths?: number; endDate?: string },
-    scope: TenantScope,
-  ): Promise<QuoteResult> {
-    const em = this.em
+    scope: TenantScope, em: EntityManager, cpqConfig: CpqQuoteConfiguration): Promise<QuoteResult> {
+    // ARC markers (`_arc*`) are server-owned: the quote page echoes the line's
+    // stored configuration (markers included) back, so drop them here and
+    // re-apply the server's own markers below.
+    update = { ...update, configuration: stripArcMarkers(update.configuration) }
 
-    const cpqConfig = await this.loadCpqConfig(em, quoteId, scope)
     const salesQuote = await this.loadSalesQuote(em, cpqConfig.quoteId, scope)
 
     if (TERMINAL_STATUSES.includes(cpqConfig.cpqStatus as CpqStatus)) {
@@ -345,6 +390,9 @@ export class DefaultCpqQuotingService {
       deletedAt: null,
     })
     if (!lineConfig) throw new QuotingError(404, 'Quote line not found')
+    if (isArcCancelledLine(lineConfig, cpqConfig.quoteType)) {
+      throw new QuotingError(409, 'This subscription item is marked for removal — restore it before changing it')
+    }
 
     const quoteLine = await em.findOne(SalesQuoteLine, {
       id: lineId,
@@ -386,10 +434,11 @@ export class DefaultCpqQuotingService {
       validationErrors = validation.errors
     }
 
-    // Preserve XD-250 ARC markers across edits — the UI doesn't echo them
-    // back in `update.configuration`, so we'd lose `_arcMirroredFromItemId` /
-    // `_arcMirroredName` (and downstream "Mirrored from existing subscription
-    // item" rendering, plus the recalc / validate paths that key off them).
+    // Preserve XD-250 ARC markers across edits — client-sent markers were
+    // stripped above, so carry `_arcMirroredFromItemId` / `_arcMirroredName`
+    // over from the stored configuration (downstream "Mirrored from existing
+    // subscription item" rendering plus the recalc / validate paths key off
+    // them).
     const existingCfg = lineConfig.configuration as Record<string, unknown> | null
     const arcMarkers: Record<string, unknown> = {}
     if (existingCfg?._arcMirroredFromItemId !== undefined) {
@@ -398,6 +447,26 @@ export class DefaultCpqQuotingService {
     if (existingCfg?._arcMirroredName !== undefined) {
       arcMarkers._arcMirroredName = existingCfg._arcMirroredName
     }
+    // A frozen Amend mirror line keeps the subscription's stored price until
+    // a pricing input changes; then it is unfrozen, marked re-priced and
+    // priced as usual.
+    const wasFrozen = isFrozenAmendMirrorLine(existingCfg, cpqConfig.quoteType)
+    const pricingInputsChanged =
+      wasFrozen &&
+      arcPricingInputsChanged(
+        {
+          configuration: existingCfg,
+          quantity: lineConfig.quantity,
+          termMonths: lineConfig.termMonths,
+          startDate: lineConfig.startDate,
+          endDate: lineConfig.endDate,
+          usageEstimates: lineConfig.usageEstimates,
+        },
+        update,
+      )
+    const staysFrozen = wasFrozen && !pricingInputsChanged
+    if (staysFrozen) arcMarkers[ARC_PRICE_FROZEN_KEY] = true
+    if (pricingInputsChanged || existingCfg?.[ARC_REPRICED_KEY] === true) arcMarkers[ARC_REPRICED_KEY] = true
     update.configuration = { ...update.configuration, ...arcMarkers }
     mergedConfig._arcMirroredFromItemId = arcMarkers._arcMirroredFromItemId
     mergedConfig._arcMirroredName = arcMarkers._arcMirroredName
@@ -409,7 +478,7 @@ export class DefaultCpqQuotingService {
     // to "incomplete" with mrcTotal=0.
     const isArcMirrored = !!(arcMarkers._arcMirroredFromItemId)
     let charges: ResolvedCharge[]
-    if (lineConfig.offeringId || lineConfig.productId) {
+    if ((lineConfig.offeringId || lineConfig.productId) && !staysFrozen) {
       charges = await this.pricingService.resolveProductCharges({
         offeringId: lineConfig.offeringId ?? undefined,
         productId: lineConfig.productId ?? undefined,
@@ -467,9 +536,11 @@ export class DefaultCpqQuotingService {
   // ─── Remove Quote Item ─────────────────────────────────────────
 
   async removeQuoteItem(quoteId: string, lineId: string, scope: TenantScope): Promise<QuoteResult> {
-    const em = this.em
+    return this.writeQuote(quoteId, scope, (em, quote) => this.removeQuoteItemInTransaction(quoteId, lineId, scope, em, quote), undefined, undefined, LINE_EVENTS)
+  }
+
+  private async removeQuoteItemInTransaction(quoteId: string, lineId: string, scope: TenantScope, em: EntityManager, cpqConfig: CpqQuoteConfiguration): Promise<QuoteResult> {
 
-    const cpqConfig = await this.loadCpqConfig(em, quoteId, scope)
     const salesQuote = await this.loadSalesQuote(em, cpqConfig.quoteId, scope)
 
     if (TERMINAL_STATUSES.includes(cpqConfig.cpqStatus as CpqStatus)) {
@@ -486,37 +557,92 @@ export class DefaultCpqQuotingService {
     })
     if (!lineConfig) throw new QuotingError(404, 'Quote line not found')
 
-    const now = new Date()
-    lineConfig.deletedAt = now
+    if (removalCancelsItem(lineConfig, cpqConfig.quoteType)) {
+      // Amend / Renew: a line mirroring a live subscription item becomes a
+      // `cancel` line so activation terminates the item (see arcLineRemoval.ts).
+      if (lineConfig.action === 'cancel') {
+        throw new QuotingError(409, 'This subscription item is already marked for removal')
+      }
+      const plan = planArcLineRemoval(lineConfig, await loadLines(em, cpqConfig.id, scope), cpqConfig.quoteType)
+      for (const root of plan.removeRoots) await removeQuoteLineTree(em, cpqConfig.id, root, scope)
+      await withAtomicFlush(em, [() => {
+        for (const line of plan.cancel) {
+          line.action = 'cancel'
+          line.charges = []
+          line.nrcTotal = '0'
+          line.mrcTotal = '0'
+          line.isConfigured = true
+          line.validationErrors = null
+        }
+      }])
+    } else {
+      await removeQuoteLineTree(em, cpqConfig.id, lineConfig, scope)
+    }
 
-    // Soft-delete children
-    const children = await em.find(CpqQuoteLineConfiguration, {
-      parentLineId: lineId,
-      quoteConfigurationId: cpqConfig.id,
-      organizationId: scope.organizationId,
-      tenantId: scope.tenantId,
-      deletedAt: null,
-    })
-    for (const child of children) {
-      child.deletedAt = now
-      // Also soft-delete the SalesQuoteLine
-      const childSalesLine = await em.findOne(SalesQuoteLine, {
-        id: child.quoteLineId,
-        organizationId: scope.organizationId,
-        tenantId: scope.tenantId,
-      })
-      if (childSalesLine) childSalesLine.deletedAt = now
+    return this.recalculateInternal(em, cpqConfig, salesQuote, scope, true)
+  }
+
+  // ─── Restore a removed subscription item (Amend / Renew) ───────
+
+  async restoreQuoteItem(quoteId: string, lineId: string, scope: TenantScope): Promise<QuoteResult> {
+    return this.writeQuote(quoteId, scope, (em, quote) => this.restoreQuoteItemInTransaction(lineId, scope, em, quote), undefined, undefined, LINE_EVENTS)
+  }
+
+  private async restoreQuoteItemInTransaction(lineId: string, scope: TenantScope, em: EntityManager, cpqConfig: CpqQuoteConfiguration): Promise<QuoteResult> {
+    const salesQuote = await this.loadSalesQuote(em, cpqConfig.quoteId, scope)
+
+    if (TERMINAL_STATUSES.includes(cpqConfig.cpqStatus as CpqStatus)) {
+      throw new QuotingError(409, `Cannot modify quote in '${cpqConfig.cpqStatus}' status`)
     }
 
-    // Soft-delete the SalesQuoteLine
-    const salesLine = await em.findOne(SalesQuoteLine, {
-      id: lineId,
+    const lines = await loadLines(em, cpqConfig.id, scope)
+    const lineConfig = lines.find((line) => line.quoteLineId === lineId)
+    if (!lineConfig) throw new QuotingError(404, 'Quote line not found')
+    if (!isArcCancelledLine(lineConfig, cpqConfig.quoteType) || !isArcMirrorLine(lineConfig.configuration, cpqConfig.quoteType)) {
+      throw new QuotingError(409, 'Only subscription items marked for removal can be restored')
+    }
+
+    const plan = planArcLineRestore(lineConfig, lines, cpqConfig.quoteType)
+    if (!plan.ok) throw new QuotingError(409, 'Restore the parent item first')
+
+    const itemIdOf = (line: CpqQuoteLineConfiguration) =>
+      line.sourceSubscriptionItemId ?? ((line.configuration as Record<string, unknown> | null)?._arcMirroredFromItemId as string | undefined) ?? null
+    const itemIds = plan.restore.map(itemIdOf).filter((id): id is string => !!id)
+    const items = itemIds.length
+      ? await em.find(CpqInventorySubscriptionItem, { id: { $in: itemIds }, organizationId: scope.organizationId, tenantId: scope.tenantId, deletedAt: null })
+      : []
+    const itemById = new Map(items.map((item) => [item.id, item]))
+    const salesLines = await em.find(SalesQuoteLine, {
+      id: { $in: plan.restore.map((line) => line.quoteLineId) },
       organizationId: scope.organizationId,
       tenantId: scope.tenantId,
+      deletedAt: null,
     })
-    if (salesLine) salesLine.deletedAt = now
+    const salesLineById = new Map(salesLines.map((line) => [line.id, line]))
 
-    await em.flush()
+    const restores = plan.restore.map((line) => {
+      const itemId = itemIdOf(line)
+      const item = itemId ? itemById.get(itemId) : undefined
+      if (!item || ['terminated', 'expired', 'superseded'].includes(item.status)) {
+        throw new QuotingError(409, 'The subscription item is no longer active and cannot be restored')
+      }
+      return { line, item }
+    })
+    const arcType = cpqConfig.quoteType as 'amend' | 'renew'
+    await withAtomicFlush(em, [() => {
+      for (const { line, item } of restores) {
+        line.action = 'modify'
+        line.configuration = buildArcMirrorConfiguration(item.configuration, item, arcType)
+        line.charges = pickArcMirrorCharges(item, cpqConfig.currencyCode)
+        line.quantity = item.quantity
+        line.nrcTotal = String(item.nrcAmount ?? 0)
+        line.mrcTotal = String(item.mrcAmount)
+        line.isConfigured = true
+        line.validationErrors = null
+        const salesLine = salesLineById.get(line.quoteLineId)
+        if (salesLine) salesLine.quantity = String(item.quantity)
+      }
+    }])
 
     return this.recalculateInternal(em, cpqConfig, salesQuote, scope, true)
   }
@@ -542,20 +668,46 @@ export class DefaultCpqQuotingService {
   // ─── Recalculate ───────────────────────────────────────────────
 
   async recalculate(quoteId: string, options: { save: boolean }, scope: TenantScope): Promise<QuoteResult> {
-    const em = options.save ? this.em.fork() : this.em
+    if (options.save) {
+      return this.writeQuote(quoteId, scope, (em, quote) => this.recalculateFromConfig(em, quote, scope, true), undefined,
+        (quote) => {
+          if (TERMINAL_STATUSES.includes(quote.cpqStatus as CpqStatus)) throw new QuotingError(409, `Cannot recalculate quote in '${quote.cpqStatus}' status`)
+        })
+    }
+    const cpqConfig = await this.loadCpqConfig(this.em, quoteId, scope)
+    return this.recalculateFromConfig(this.em, { ...cpqConfig } as CpqQuoteConfiguration, scope, false)
+  }
+
+  private async recalculateFromConfig(em: EntityManager, cpqConfig: CpqQuoteConfiguration, scope: TenantScope, save: boolean): Promise<QuoteResult> {
+
+    // A terminal quote's stored prices are final (accepted quotes are the
+    // basis for order conversion) — a saved recalculation must not move them.
+    if (save && TERMINAL_STATUSES.includes(cpqConfig.cpqStatus as CpqStatus)) {
+      throw new QuotingError(409, `Cannot recalculate quote in '${cpqConfig.cpqStatus}' status`)
+    }
 
-    const cpqConfig = await this.loadCpqConfig(em, quoteId, scope)
     const salesQuote = await this.loadSalesQuote(em, cpqConfig.quoteId, scope)
 
-    return this.recalculateInternal(em, cpqConfig, salesQuote, scope, options.save)
+    return this.recalculateInternal(em, cpqConfig, salesQuote, scope, save)
   }
 
   // ─── Clone Quote ───────────────────────────────────────────────
 
   async cloneQuote(quoteId: string, scope: TenantScope): Promise<QuoteResult> {
-    const em = this.em
+    const created: { quote?: CpqQuoteConfiguration } = {}
+    const result = await this.writeQuote(quoteId, scope,
+      (em, quote) => this.cloneQuoteInTransaction(quoteId, scope, em, quote, created),
+      undefined, undefined, { pricingCause: 'clone' })
+    // The copy is a new aggregate: its first committed snapshot is a pricing signal.
+    if (created.quote) await emitQuoteWriteEvents(null, created.quote, { pricingCause: 'clone' })
+    return result
+  }
+
+  private async cloneQuoteInTransaction(
+    quoteId: string, scope: TenantScope, em: EntityManager, original: CpqQuoteConfiguration,
+    created: { quote?: CpqQuoteConfiguration } = {},
+  ): Promise<QuoteResult> {
 
-    const original = await this.loadCpqConfig(em, quoteId, scope)
     const originalQuote = await this.loadSalesQuote(em, original.quoteId, scope)
 
     // Generate new quote number
@@ -589,11 +741,13 @@ export class DefaultCpqQuotingService {
 
     // Create new CpqQuoteConfiguration
     const newCpqConfig = em.create(CpqQuoteConfiguration, {
+      id: crypto.randomUUID(),
       organizationId: scope.organizationId,
       tenantId: scope.tenantId,
       quoteId: newSalesQuoteId,
       customerId: original.customerId,
       cpqStatus: 'new',
+      pricingRevision: 1,
       version: original.version + 1,
       parentQuoteId: original.id,
       currencyCode: original.currencyCode,
@@ -602,6 +756,8 @@ export class DefaultCpqQuotingService {
       pricingSummary: emptyPricingSummary(original.currencyCode),
     })
     em.persist(newCpqConfig)
+    created.quote = newCpqConfig
+    await em.flush()
 
     // Copy all lines
     const originalLines = await em.find(CpqQuoteLineConfiguration, {
@@ -663,7 +819,8 @@ export class DefaultCpqQuotingService {
         startDate: origLine.startDate,
         termMonths: origLine.termMonths,
         endDate: origLine.endDate,
-        configuration: { ...origLine.configuration },
+        // A clone is a new quote: quote-only ARC pricing markers don't apply.
+        configuration: { ...stripQuoteOnlyArcMarkers(origLine.configuration) },
         quantity: origLine.quantity,
         charges: origLine.charges ? [...origLine.charges] : null,
         nrcTotal: origLine.nrcTotal,
@@ -695,15 +852,21 @@ export class DefaultCpqQuotingService {
     await em.flush()
 
     // Recalculate the new quote at current rates
+    await cloneQuoteAdjustments(em, original.id, newCpqConfig, lineIdMap, scope)
+    await em.flush()
+
     return this.recalculateInternal(em, newCpqConfig, newSalesQuote, scope, true)
   }
 
   // ─── Transition Status ─────────────────────────────────────────
 
-  async transitionStatus(quoteId: string, targetStatus: string, scope: TenantScope): Promise<QuoteResult> {
-    const em = this.em
+  async transitionStatus(quoteId: string, targetStatus: string, scope: TenantScope, actorUserId: string | null = null): Promise<QuoteResult> {
+    return this.writeQuote(quoteId, scope, (em, quote) => this.transitionStatusInTransaction(quoteId, targetStatus, scope, em, quote),
+      undefined, undefined, { pricingCause: 'recalculate', statusCause: 'manual', actorUserId })
+  }
+
+  private async transitionStatusInTransaction(quoteId: string, targetStatus: string, scope: TenantScope, em: EntityManager, cpqConfig: CpqQuoteConfiguration): Promise<QuoteResult> {
 
-    const cpqConfig = await this.loadCpqConfig(em, quoteId, scope)
     const salesQuote = await this.loadSalesQuote(em, cpqConfig.quoteId, scope)
 
     const currentStatus = cpqConfig.cpqStatus as CpqStatus
@@ -725,7 +888,7 @@ export class DefaultCpqQuotingService {
       targetStatus === 'with_customer'
     const quoteType = cpqConfig.quoteType ?? 'new'
     if (isSubmitForApproval && quoteType !== 'new') {
-      const validation = await this.validateArcQuote(quoteId, scope)
+      const validation = await this.validateArcQuote(quoteId, scope, em)
       if (!validation.ok) {
         throw new QuotingError(
           422,
@@ -747,6 +910,28 @@ export class DefaultCpqQuotingService {
     return this.buildQuoteResult(em, cpqConfig, salesQuote, lines)
   }
 
+  private async writeQuote(
+    quoteId: string,
+    scope: TenantScope,
+    execute: (em: EntityManager, quote: CpqQuoteConfiguration) => Promise<QuoteResult>,
+    expectedRevision?: number,
+    validate?: (quote: CpqQuoteConfiguration) => void,
+    events: QuoteWriteEvents = { pricingCause: 'recalculate' },
+  ): Promise<QuoteResult> {
+    return withQuotePricingWrite(this.em, quoteId, scope, execute,
+      (status, message) => new QuotingError(status, message), expectedRevision, validate, events)
+  }
+
+  /** Called by adjustment commands that already own the quote lock/revision. */
+  async recalculateLockedQuote(
+    em: EntityManager, quote: CpqQuoteConfiguration, scope: TenantScope,
+    save = true, adjustments?: PriceAdjustment[],
+  ): Promise<QuoteResult> {
+    const salesQuote = await this.loadSalesQuote(em, quote.quoteId, scope)
+    const config = save ? quote : { ...quote } as CpqQuoteConfiguration
+    return this.recalculateInternal(em, config, salesQuote, scope, save, adjustments)
+  }
+
   // ─── Internal: Recalculate ─────────────────────────────────────
 
   private async recalculateInternal(
@@ -755,6 +940,7 @@ export class DefaultCpqQuotingService {
     salesQuote: SalesQuote,
     scope: TenantScope,
     save: boolean,
+    draftAdjustments?: PriceAdjustment[],
   ): Promise<QuoteResult> {
     const lineConfigs = await em.find(CpqQuoteLineConfiguration, {
       quoteConfigurationId: cpqConfig.id,
@@ -800,7 +986,7 @@ export class DefaultCpqQuotingService {
       }
 
       let validationErrors: ValidationError[] = []
-      if (lineConfig.offeringId) {
+      if (lineConfig.offeringId && !isArcCancelledLine(lineConfig, cpqConfig.quoteType)) {
         const validation = await this.validationService.validateOfferingConfiguration({
           offeringId: lineConfig.offeringId,
           configuration: lineConfig.configuration,
@@ -817,8 +1003,16 @@ export class DefaultCpqQuotingService {
       // line to "incomplete".
       const cfgRecord = lineConfig.configuration as Record<string, unknown> | null
       const isArcMirrored = !!(cfgRecord?._arcMirroredFromItemId)
+      // Frozen Amend mirror lines keep the subscription item's stored charges
+      // (see arcPriceFreeze.ts) — re-pricing them would silently move the
+      // contracted price of items the amendment does not touch.
+      const isFrozen = isFrozenAmendMirrorLine(cfgRecord, cpqConfig.quoteType)
       let charges: ResolvedCharge[]
-      if (lineConfig.offeringId || lineConfig.productId) {
+      if (isArcCancelledLine(lineConfig, cpqConfig.quoteType)) {
+        // Item marked for removal: it leaves the subscription, so it adds
+        // nothing to the quote (its current price is shown via `arcSource`).
+        charges = []
+      } else if ((lineConfig.offeringId || lineConfig.productId) && !isFrozen) {
         charges = await this.pricingService.resolveProductCharges({
           offeringId: lineConfig.offeringId ?? undefined,
           productId: lineConfig.productId ?? undefined,
@@ -844,37 +1038,72 @@ export class DefaultCpqQuotingService {
 
       computedLines.push({ lineConfig, charges, nrcTotal, mrcTotal, usageEstimates, usageTotalEstimated, validationErrors, isConfigured })
 
+    }
+    const adjustments = draftAdjustments ?? await loadQuoteAdjustments(em, cpqConfig.id, scope)
+    const adjusted = resolveManualAdjustments(computedLines.map(({ lineConfig, charges }) => ({
+      lineId: lineConfig.quoteLineId, parentLineId: lineConfig.parentLineId ?? null,
+      enginePriced: !!(lineConfig.offeringId || lineConfig.productId),
+      mirrored: isArcMirrorLine(lineConfig.configuration, cpqConfig.quoteType), charges,
+    })), adjustments, cpqConfig.currencyCode)
+    const adjustedById = new Map(adjusted.lines.map((line) => [line.lineId, line]))
+    const computedIds = new Set(computedLines.map((line) => line.lineConfig.quoteLineId))
+    for (const computed of computedLines) {
+      const { lineConfig } = computed
+      // No adjustments: preserve legacy/frozen snapshots byte-for-byte on disk.
+      if (adjustments.length) computed.charges = adjustedById.get(lineConfig.quoteLineId)!.charges
+      const adjustmentErrors = adjusted.errors.filter((error) => error.quoteLineId === lineConfig.quoteLineId)
+      if (adjustmentErrors.length) {
+        computed.isConfigured = false
+        allValid = false
+        const errors = adjustmentErrors.map((error) => ({ message: error.code, attribute: error.chargeCode, lineId: error.quoteLineId, adjustmentId: error.adjustmentId }))
+        computed.validationErrors.push(...errors)
+        allErrors.push(...errors)
+      }
+      Object.assign(computed, computeLineTotals(computed.charges, lineConfig.quantity,
+        lineConfig.usageEstimates?.map((entry) => ({ chargeCode: entry.chargeCode, estimatedQuantity: entry.estimatedQuantity }))))
+      const { charges, nrcTotal, mrcTotal, usageEstimates, usageTotalEstimated, validationErrors, isConfigured } = computed
       if (save) {
-        em.assign(lineConfig, {
-          charges: charges as unknown as Array<Record<string, unknown>>,
-          nrcTotal: String(nrcTotal),
-          mrcTotal: String(mrcTotal),
-          usageEstimates: usageEstimates ?? null,
-          usageTotalEstimated: usageTotalEstimated != null ? String(usageTotalEstimated) : null,
-          validationErrors: validationErrors.length > 0 ? validationErrors as unknown as Array<Record<string, unknown>> : null,
-          isConfigured,
-        })
-
-        const salesLine = await em.findOne(SalesQuoteLine, {
-          id: lineConfig.quoteLineId,
-          organizationId: scope.organizationId,
-          tenantId: scope.tenantId,
-        })
-        if (salesLine) {
-          const perInstanceNrc = charges.filter((c) => c.chargeType === 'nrc').reduce((s, c) => s + (c.totalPrice ?? 0), 0)
-          const perInstanceMrc = charges.filter((c) => c.chargeType === 'mrc').reduce((s, c) => s + (c.totalPrice ?? 0), 0)
-          const unitPriceNet = perInstanceNrc + perInstanceMrc
-          em.assign(salesLine, {
-            quantity: String(lineConfig.quantity),
-            unitPriceNet: String(unitPriceNet),
-            unitPriceGross: String(unitPriceNet),
-            totalNetAmount: String(unitPriceNet * lineConfig.quantity),
-            totalGrossAmount: String(unitPriceNet * lineConfig.quantity),
-            updatedAt: new Date(),
-          })
-        }
+        await withAtomicFlush(em, [
+          () => {
+            em.assign(lineConfig, {
+              charges: charges as unknown as Array<Record<string, unknown>>,
+              nrcTotal: String(nrcTotal),
+              mrcTotal: String(mrcTotal),
+              usageEstimates: usageEstimates ?? null,
+              usageTotalEstimated: usageTotalEstimated != null ? String(usageTotalEstimated) : null,
+              validationErrors: validationErrors.length > 0 ? validationErrors as unknown as Array<Record<string, unknown>> : null,
+              isConfigured,
+            })
+          },
+          async () => {
+            const salesLine = await em.findOne(SalesQuoteLine, {
+              id: lineConfig.quoteLineId,
+              organizationId: scope.organizationId,
+              tenantId: scope.tenantId,
+            })
+            if (salesLine) {
+              const perInstanceNrc = charges.filter((charge) => charge.chargeType === 'nrc').reduce((sum, charge) => sum + (charge.totalPrice ?? 0), 0)
+              const perInstanceMrc = charges.filter((charge) => charge.chargeType === 'mrc').reduce((sum, charge) => sum + (charge.totalPrice ?? 0), 0)
+              const unitPriceNet = perInstanceNrc + perInstanceMrc
+              em.assign(salesLine, {
+                quantity: String(lineConfig.quantity),
+                unitPriceNet: String(unitPriceNet),
+                unitPriceGross: String(unitPriceNet),
+                totalNetAmount: String(unitPriceNet * lineConfig.quantity),
+                totalGrossAmount: String(unitPriceNet * lineConfig.quantity),
+                updatedAt: new Date(),
+              })
+            }
+          },
+        ])
       }
     }
+    // A missing line target must still invalidate the quote (normally removal
+    // soft-deletes its adjustments in the same aggregate transaction).
+    for (const error of adjusted.errors.filter((entry) => !computedIds.has(entry.quoteLineId))) {
+      allValid = false
+      allErrors.push({ message: error.code, attribute: error.chargeCode, lineId: error.quoteLineId, adjustmentId: error.adjustmentId })
+    }
 
     const relationshipErrors = await this.validationService.validateRelationships({
       lines: lineConfigs.map((l) => ({
@@ -903,6 +1132,10 @@ export class DefaultCpqQuotingService {
 
     // Build pricing summary from freshly computed data (not from stale entity fields)
     const pricingSummary = computePricingSummaryFromComputed(computedLines, cpqConfig.currencyCode)
+    Object.assign(pricingSummary, computeWaterfallSummary(computedLines.map(({ lineConfig, charges }) => ({
+      lineId: lineConfig.quoteLineId, quantity: lineConfig.quantity, termMonths: lineConfig.termMonths,
+      includeInDeal: !isArcMirrorLine(lineConfig.configuration, cpqConfig.quoteType), charges,
+    })), adjustments, cpqConfig.currencyCode))
 
     const validationResult = { valid: allValid, errors: allErrors }
 
@@ -923,7 +1156,9 @@ export class DefaultCpqQuotingService {
       await em.flush()
     }
 
-    return this.buildQuoteResultFromComputed(em, cpqConfig, salesQuote, computedLines, validationResult, pricingSummary)
+    const result = await this.buildQuoteResultFromComputed(em, cpqConfig, salesQuote, computedLines, validationResult, pricingSummary)
+    result.adjustmentErrors = adjusted.errors
+    return result
   }
 
   // ─── Helpers ───────────────────────────────────────────────────
@@ -1039,7 +1274,7 @@ export class DefaultCpqQuotingService {
         mrcTotal: Number(lc.mrcTotal),
         usageEstimates: lc.usageEstimates ?? null,
         usageTotalEstimated: lc.usageTotalEstimated != null ? Number(lc.usageTotalEstimated) : null,
-        charges: (lc.charges ?? []) as unknown as ResolvedCharge[],
+        charges: ((lc.charges ?? []) as unknown as ResolvedCharge[]).map(withChargeWaterfall),
         isConfigured: lc.isConfigured,
         validationErrors: lc.validationErrors as unknown as ValidationError[] ?? null,
         arcSource: pickArcSource(lc, arcSourceMap),
@@ -1049,6 +1284,13 @@ export class DefaultCpqQuotingService {
 
     const finalValidation = validationResult ?? (cpqConfig.validationResult as { valid: boolean; errors: ValidationError[] }) ?? { valid: true, errors: [] }
     const finalPricing = pricingSummary ?? computePricingSummary(lineConfigs, cpqConfig.currencyCode)
+    if (!pricingSummary) {
+      const adjustments = await loadQuoteAdjustments(em, cpqConfig.id, { organizationId: cpqConfig.organizationId, tenantId: cpqConfig.tenantId })
+      Object.assign(finalPricing, computeWaterfallSummary(lines.map((line) => ({
+        lineId: line.lineId, quantity: line.quantity, termMonths: line.termMonths,
+        includeInDeal: !isArcMirrorLine(line.configuration, cpqConfig.quoteType), charges: line.charges,
+      })), adjustments, cpqConfig.currencyCode))
+    }
 
     const { customerName, convertedOrderId } = await resolveQuoteSideData(em, cpqConfig)
 
@@ -1060,6 +1302,7 @@ export class DefaultCpqQuotingService {
       customerName,
       cpqStatus: cpqConfig.cpqStatus,
       version: cpqConfig.version,
+      pricingRevision: cpqConfig.pricingRevision ?? 0,
       parentQuoteId: cpqConfig.parentQuoteId ?? null,
       currencyCode: cpqConfig.currencyCode,
       convertedOrderId,
@@ -1136,7 +1379,7 @@ export class DefaultCpqQuotingService {
         mrcTotal,
         usageEstimates,
         usageTotalEstimated,
-        charges,
+        charges: charges.map(withChargeWaterfall),
         isConfigured,
         validationErrors: validationErrors.length > 0 ? validationErrors : null,
         arcSource: pickArcSource(lc, arcSourceMap),
@@ -1154,6 +1397,7 @@ export class DefaultCpqQuotingService {
       customerName,
       cpqStatus: cpqConfig.cpqStatus,
       version: cpqConfig.version,
+      pricingRevision: cpqConfig.pricingRevision ?? 0,
       parentQuoteId: cpqConfig.parentQuoteId ?? null,
       currencyCode: cpqConfig.currencyCode,
       convertedOrderId,
@@ -1272,6 +1516,7 @@ function aggregateAdjustmentTotals(allCharges: ResolvedCharge[]): { discountTota
   for (const charge of allCharges) {
     if (!charge.adjustments) continue
     for (const adj of charge.adjustments) {
+      if (adj.origin === 'manual') continue
       if (adj.delta < 0) {
         discountTotal += Math.abs(adj.delta) * (charge.quantity ?? 1)
       } else if (adj.delta > 0) {
@@ -1373,8 +1618,13 @@ function computePricingSummaryFromComputed(
   }
 }
 
+const LINE_EVENTS: QuoteWriteEvents = { pricingCause: 'line' }
+
 function emptyPricingSummary(currencyCode: string): Record<string, unknown> {
   return {
+    // A new quote starts with a real baseline hash, so its first priced line is
+    // a pricing change; only pre-feature quotes have no stored hash.
+    snapshotHash: computeWaterfallSummary([], [], currencyCode).snapshotHash,
     nrcTotal: 0,
     mrcTotal: 0,
     usageCharges: [],
@@ -1387,7 +1637,17 @@ function emptyPricingSummary(currencyCode: string): Record<string, unknown> {
 
 // ─── Error class ──────────────────────────────────────────────────
 
+// Cross-realm brand. Next bundles this package once per server layer (page
+// SSR vs route handler), and the DI container is shared through globalThis,
+// so a route handler can catch a QuotingError built from the *other* copy of
+// this class — `instanceof` is then false and a typed 404/409 turns into a
+// 500. `Symbol.for` resolves to the same symbol in every copy. Same approach
+// as `isCrudHttpError` in @open-mercato/shared. Use `isQuotingError`.
+const QUOTING_ERROR_BRAND = Symbol.for('@dainamite/cpq/QuotingError')
+
 export class QuotingError extends Error {
+  readonly [QUOTING_ERROR_BRAND] = true
+
   constructor(
     public status: number,
     message: string,
@@ -1406,6 +1666,10 @@ export class QuotingError extends Error {
   }
 }
 
+export function isQuotingError(err: unknown): err is QuotingError {
+  return !!err && typeof err === 'object' && (err as Record<symbol, unknown>)[QUOTING_ERROR_BRAND] === true
+}
+
 // ─── ARC orchestration (XD-250) ────────────────────────────────────
 //
 // All ARC user-journey logic lives on the CPQ Quote module:
@@ -1544,7 +1808,7 @@ declare module './cpqQuotingService' {
     ): Promise<TargetSubscriptionView>
     setCancelMeta(quoteId: string, meta: CancelMetaInput, scope: TenantScope): Promise<QuoteResult>
     setMergeMeta(quoteId: string, meta: MergeMetaInput, scope: TenantScope): Promise<QuoteResult>
-    validateArcQuote(quoteId: string, scope: TenantScope): Promise<ArcQuoteValidationResult>
+    validateArcQuote(quoteId: string, scope: TenantScope, transactionEm?: EntityManager): Promise<ArcQuoteValidationResult>
   }
 }
 
@@ -1908,50 +2172,51 @@ DefaultCpqQuotingService.prototype.detachTargetSubscription = async function (
   scope: TenantScope,
 ): Promise<{ ok: true }> {
   const em = (this as unknown as { em: EntityManager }).em
-  const cpqConfig = await loadCpqConfigStrict(em, quoteId, scope)
-  ensureEditable(cpqConfig)
-
-  const target = await em.findOne(CpqQuoteTargetSubscription, {
-    id: targetId,
-    quoteId: cpqConfig.id,
-    organizationId: scope.organizationId,
-    tenantId: scope.tenantId,
-    deletedAt: null,
-  })
-  if (!target) throw new QuotingError(404, 'Target subscription not found')
-
-  // Drop any quote lines that pointed at this target.
-  const lines = await em.find(CpqQuoteLineConfiguration, {
-    quoteConfigurationId: cpqConfig.id,
-    targetSubscriptionId: target.subscriptionId,
-    organizationId: scope.organizationId,
-    tenantId: scope.tenantId,
-    deletedAt: null,
-  })
-  const now = new Date()
-  for (const line of lines) {
-    line.deletedAt = now
-    const salesLine = await em.findOne(SalesQuoteLine, { id: line.quoteLineId })
-    if (salesLine) salesLine.deletedAt = now
-  }
-
-  target.deletedAt = now
-
-  // Auto-revert merge mode if only one renew target remains.
-  if (target.quoteType === 'renew') {
-    const remaining = await em.find(CpqQuoteTargetSubscription, {
+  // Detaching removes priced lines (rep-added lines may carry negotiated
+  // prices), so it takes the same aggregate lock and revision bump as any
+  // other pricing write and re-prices the remaining lines.
+  await withQuotePricingWrite(em, quoteId, scope, async (tx, cpqConfig) => {
+    const target = await tx.findOne(CpqQuoteTargetSubscription, {
+      id: targetId,
       quoteId: cpqConfig.id,
       organizationId: scope.organizationId,
       tenantId: scope.tenantId,
       deletedAt: null,
-      id: { $ne: target.id },
     })
-    if (remaining.length === 1) {
-      remaining[0].mergeAction = 'standalone'
+    if (!target) throw new QuotingError(404, 'Target subscription not found')
+
+    // Drop quote lines that pointed at this target, with their bundle
+    // children, sales lines and price adjustments.
+    const lines = await tx.find(CpqQuoteLineConfiguration, {
+      quoteConfigurationId: cpqConfig.id,
+      targetSubscriptionId: target.subscriptionId,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      deletedAt: null,
+    })
+    for (const line of lines) {
+      if (line.deletedAt) continue
+      await removeQuoteLineTree(tx, cpqConfig.id, line, scope)
     }
-  }
 
-  await em.flush()
+    // Read the remaining renew targets before mutating, so no query runs
+    // between a scalar change and its flush.
+    const remaining = target.quoteType === 'renew'
+      ? await tx.find(CpqQuoteTargetSubscription, {
+        quoteId: cpqConfig.id,
+        organizationId: scope.organizationId,
+        tenantId: scope.tenantId,
+        deletedAt: null,
+        id: { $ne: target.id },
+      })
+      : []
+    await withAtomicFlush(tx, [() => {
+      target.deletedAt = new Date()
+      // Auto-revert merge mode if only one renew target remains.
+      if (remaining.length === 1) remaining[0].mergeAction = 'standalone'
+    }])
+    await this.recalculateLockedQuote(tx, cpqConfig, scope, true)
+  }, (status, message) => new QuotingError(status, message), undefined, ensureEditable, { pricingCause: 'line' })
   return { ok: true }
 }
 
@@ -2048,8 +2313,9 @@ DefaultCpqQuotingService.prototype.validateArcQuote = async function (
   this: DefaultCpqQuotingService,
   quoteId: string,
   scope: TenantScope,
+  transactionEm?: EntityManager,
 ): Promise<ArcQuoteValidationResult> {
-  const em = (this as unknown as { em: EntityManager }).em
+  const em = transactionEm ?? (this as unknown as { em: EntityManager }).em
   const cpqConfig = await loadCpqConfigStrict(em, quoteId, scope)
   const errors: string[] = []
 
@@ -2352,6 +2618,7 @@ async function mapTargetView(
 
 function emptyArcPricingSummary(currencyCode: string): Record<string, unknown> {
   return {
+    snapshotHash: computeWaterfallSummary([], [], currencyCode).snapshotHash,
     nrcTotal: 0,
     mrcTotal: 0,
     usageCharges: [],
@@ -2522,11 +2789,7 @@ async function mirrorTargetSubscriptionItems(
       startDate: null,
       termMonths: null,
       endDate: null,
-      configuration: {
-        ...item.configuration,
-        _arcMirroredFromItemId: item.id,
-        _arcMirroredName: item.name,
-      },
+      configuration: buildArcMirrorConfiguration(item.configuration, item, quoteType),
       quantity: item.quantity,
       charges: pickArcMirrorCharges(item, sub.currencyCode),
       nrcTotal: String(item.nrcAmount ?? 0),