@dainamite/cpq 0.5.0 → 0.6.0

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

@@ -0,0 +1,47 @@
+import { computeWaterfallSummary } from './priceAdjustments/pricingSnapshot'
+import { isArcMirrorLine } from './arcPriceFreeze'
+import type { PricingWaterfallSummary, ResolvedCharge } from './types'
+
+export type OrderSummaryLine = {
+  lineId: string
+  quantity: number
+  termMonths: number | null
+  configuration: Record<string, unknown> | null
+  charges: Array<Record<string, unknown>>
+}
+
+/** The quote's list / standard / offer figures and deal value, minus quote-only fields. */
+export type OrderWaterfallSummary = Omit<PricingWaterfallSummary, 'snapshotHash' | 'hasTimeBasedAdjustments'>
+
+/** Order lines store the quote's charges as plain JSON; fill the fields the waterfall needs. */
+function toResolvedCharge(charge: Record<string, unknown>): ResolvedCharge {
+  return {
+    ...charge,
+    chargeCode: String(charge.chargeCode ?? ''),
+    chargeType: (charge.chargeType ?? 'mrc') as ResolvedCharge['chargeType'],
+    unitPrice: Number(charge.unitPrice ?? 0),
+    totalPrice: charge.totalPrice == null ? null : Number(charge.totalPrice),
+  } as ResolvedCharge
+}
+
+/**
+ * The same pricing summary the source quote shows (list totals, discount
+ * depth, deal value), computed from the order's line charges, which are
+ * copied verbatim from the quote at conversion. ARC mirror lines are left out
+ * of deal value exactly as on the quote.
+ */
+export function summarizeOrderPricing(
+  lines: readonly OrderSummaryLine[],
+  quoteType: string,
+  currencyCode: string,
+): OrderWaterfallSummary {
+  const summary = computeWaterfallSummary(lines.map((line) => ({
+    lineId: line.lineId,
+    quantity: line.quantity,
+    termMonths: line.termMonths,
+    includeInDeal: !isArcMirrorLine(line.configuration, quoteType),
+    charges: line.charges.map(toResolvedCharge),
+  })), [], currencyCode)
+  const { snapshotHash: _snapshotHash, hasTimeBasedAdjustments: _timeBased, ...orderSummary } = summary
+  return orderSummary
+}

package/src/modules/cpq/services/priceAdjustments/adjustmentService.ts

@@ -0,0 +1,249 @@
+import { isArcMirrorLine } from '../arcPriceFreeze'
+import { ADJUSTMENT_TOGGLE, REASON_DICTIONARY } from '../../data/price-adjustments'
+export { ADJUSTMENT_TOGGLE, REASON_DICTIONARY } from '../../data/price-adjustments'
+import { loadQuoteAdjustments } from './loadQuoteAdjustments'
+import { randomUUID } from 'node:crypto'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import type { FeatureTogglesService } from '@open-mercato/core/modules/feature_toggles/lib/feature-flag-check'
+import { Dictionary, DictionaryEntry } from '@open-mercato/core/modules/dictionaries/data/entities'
+import { CpqOrderConfiguration, CpqQuoteConfiguration, CpqQuoteLineConfiguration, CpqQuotePriceAdjustment } from '../../data/entities'
+import { cpqPriceAdjustmentInputSchema, cpqPriceAdjustmentPatchSchema, type PriceAdjustmentInput, type PriceAdjustmentPatch } from '../../data/price-adjustments'
+import { QuotingError, type DefaultCpqQuotingService } from '../cpqQuotingService'
+import { TERMINAL_STATUSES, type CpqStatus, type QuoteResult, type TenantScope } from '../types'
+import { withQuotePricingWrite } from './quotePricingWrite'
+
+/** Quote statuses in which reps may still add / edit / delete manual adjustments. */
+const ADJUSTMENT_MUTABLE_STATUSES: readonly CpqStatus[] = ['new', 'incomplete', 'ready']
+
+
+type Dependencies = {
+  em: EntityManager
+  quotingService: DefaultCpqQuotingService
+  featureTogglesService: Pick<FeatureTogglesService, 'getBoolConfig'>
+}
+
+export function adjustmentInput(row: CpqQuotePriceAdjustment): PriceAdjustmentInput {
+  return cpqPriceAdjustmentInputSchema.parse({ level: row.level, quoteLineId: row.quoteLineId,
+    chargeCode: row.chargeCode, chargeTypeFilter: row.chargeTypeFilter, adjustmentType: row.adjustmentType,
+    value: Number(row.value), currencyCode: row.currencyCode, reasonCode: row.reasonCode, reasonNote: row.reasonNote })
+}
+export function adjustmentSnapshot(row: CpqQuotePriceAdjustment) {
+  return { id: row.id, ...adjustmentInput(row), quoteConfigurationId: row.quoteConfigurationId,
+    quoteId: row.quoteId, tenantId: row.tenantId, organizationId: row.organizationId,
+    createdByUserId: row.createdByUserId, createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(), deletedAt: row.deletedAt?.toISOString() ?? null, isActive: row.isActive }
+}
+export type AdjustmentSnapshot = ReturnType<typeof adjustmentSnapshot>
+
+type OverlapKey = { id: string; level: string; quoteLineId: string; chargeCode?: string | null; chargeTypeFilter?: string | null }
+/** Same level and target; line filters overlap when either covers all charges or both match. */
+export function adjustmentsOverlap(a: OverlapKey, b: OverlapKey): boolean {
+  if (a.id === b.id || a.level !== b.level || a.quoteLineId !== b.quoteLineId) return false
+  if (a.level === 'charge') return (a.chargeCode ?? null) === (b.chargeCode ?? null)
+  return !a.chargeTypeFilter || !b.chargeTypeFilter || a.chargeTypeFilter === b.chargeTypeFilter
+}
+export interface AdjustmentWriteResult {
+  adjustment: AdjustmentSnapshot
+  before: AdjustmentSnapshot | null
+  quote: QuoteResult
+}
+
+export class CpqAdjustmentService {
+  constructor(private readonly deps: Dependencies) {}
+
+  async enabled(tenantId: string): Promise<boolean> {
+    const flag = await this.deps.featureTogglesService.getBoolConfig(ADJUSTMENT_TOGGLE, tenantId)
+    return flag.ok && flag.value === true
+  }
+
+  async list(quoteId: string, scope: TenantScope, page: number, pageSize: number) {
+    const em = this.deps.em.fork({ clear: true, useContext: false })
+    const scoped = { ...scope, deletedAt: null }
+    const quote = await findOneWithDecryption(em, CpqQuoteConfiguration, { ...scoped, id: quoteId }, undefined, scope)
+      ?? await findOneWithDecryption(em, CpqQuoteConfiguration, { ...scoped, quoteId }, undefined, scope)
+    if (!quote) throw new QuotingError(404, 'Quote not found')
+    const filter = { ...scoped, quoteConfigurationId: quote.id, isActive: true }
+    const [rows, total, enabled, reasons] = await Promise.all([
+      findWithDecryption(em, CpqQuotePriceAdjustment, filter, { limit: pageSize, offset: (page - 1) * pageSize, orderBy: { createdAt: 'asc', id: 'asc' } }, scope),
+      em.count(CpqQuotePriceAdjustment, filter),
+      this.enabled(scope.tenantId),
+      this.reasons(em, scope),
+    ])
+    return { items: rows.map(adjustmentSnapshot), total, page, pageSize, totalPages: Math.ceil(total / pageSize), pricingRevision: quote.pricingRevision ?? 0, enabled, reasons }
+  }
+
+  /**
+   * Reason options for the adjustment dialog. Served here so reps need only
+   * `cpq.quotes.view`, not `dictionaries.view`. An inactive dictionary yields
+   * no options, matching `requireReason`.
+   */
+  async reasons(em: EntityManager, scope: TenantScope): Promise<Array<{ value: string; label: string }>> {
+    const dictionary = await findOneWithDecryption(em, Dictionary, { key: REASON_DICTIONARY, ...scope, deletedAt: null, isActive: true }, undefined, scope)
+    if (!dictionary) return []
+    const entries = await findWithDecryption(em, DictionaryEntry, { dictionary: dictionary.id, ...scope }, { orderBy: { position: 'asc', label: 'asc' } }, scope)
+    return entries.map((entry) => ({ value: entry.value, label: entry.label }))
+  }
+
+  async preview(quoteId: string, input: PriceAdjustmentInput, replaceAdjustmentId: string | undefined, scope: TenantScope) {
+    const parsed = cpqPriceAdjustmentInputSchema.parse(input)
+    await this.requireEnabled(scope)
+    const em = this.deps.em.fork({ clear: true, useContext: false })
+    const scoped = { ...scope, deletedAt: null }
+    const quote = await findOneWithDecryption(em, CpqQuoteConfiguration, { ...scoped, id: quoteId }, undefined, scope)
+      ?? await findOneWithDecryption(em, CpqQuoteConfiguration, { ...scoped, quoteId }, undefined, scope)
+    if (!quote) throw new QuotingError(404, 'Quote not found')
+    if (parsed.expectedRevision !== undefined && parsed.expectedRevision !== (quote.pricingRevision ?? 0)) throw new QuotingError(409, 'STALE_REVISION')
+    await this.assertMutable(em, quote, scope)
+    await this.requireTarget(em, quote, parsed.quoteLineId, scope)
+    const stored = await loadQuoteAdjustments(em, quote.id, scope)
+    const replaced = stored.find((row) => row.id === replaceAdjustmentId)
+    if (replaceAdjustmentId && !replaced) throw new QuotingError(404, 'Adjustment not found')
+    if (replaced && (replaced.level !== parsed.level || replaced.quoteLineId !== parsed.quoteLineId || (replaced.chargeCode ?? null) !== (parsed.chargeCode ?? null))) throw new QuotingError(422, 'Adjustment target is immutable')
+    if (!replaced || replaced.reasonCode !== parsed.reasonCode) await this.requireReason(em, parsed.reasonCode, scope)
+    const draft = { ...parsed, id: replaceAdjustmentId ?? randomUUID() }
+    const adjustments = [...stored.filter((row) => row.id !== replaceAdjustmentId), draft]
+    const result = await this.deps.quotingService.recalculateLockedQuote(em, quote, scope, false, adjustments)
+    return { quote: result, errors: result.adjustmentErrors ?? [] }
+  }
+
+  async create(quoteId: string, input: PriceAdjustmentInput, actor: string, scope: TenantScope): Promise<AdjustmentWriteResult> {
+    const parsed = cpqPriceAdjustmentInputSchema.parse(input)
+    await this.requireEnabled(scope)
+    return this.write(quoteId, scope, parsed.expectedRevision, async (em, quote) => {
+      await this.assertMutable(em, quote, scope)
+      await this.requireReason(em, parsed.reasonCode, scope)
+      await this.requireTarget(em, quote, parsed.quoteLineId, scope)
+      const id = randomUUID()
+      await this.rejectOverlap(em, quote, { id, ...parsed }, scope)
+      const row = em.create(CpqQuotePriceAdjustment, { ...scope, id, quoteConfigurationId: quote.id,
+        quoteId: quote.quoteId, ...this.values(parsed), createdByUserId: actor })
+      return this.save(em, quote, row, null, scope, true)
+    })
+  }
+
+  async update(quoteId: string, id: string, patch: PriceAdjustmentPatch, actor: string, scope: TenantScope): Promise<AdjustmentWriteResult> {
+    const parsed = cpqPriceAdjustmentPatchSchema.parse(patch)
+    await this.requireEnabled(scope)
+    return this.write(quoteId, scope, parsed.expectedRevision, async (em, quote) => {
+      await this.assertMutable(em, quote, scope)
+      const row = await this.loadRow(em, quote.id, id, scope)
+      const before = adjustmentSnapshot(row)
+      await this.requireTarget(em, quote, row.quoteLineId, scope)
+      const merged = cpqPriceAdjustmentInputSchema.parse({ ...adjustmentInput(row), ...parsed })
+      if (merged.reasonCode !== row.reasonCode) await this.requireReason(em, merged.reasonCode, scope)
+      await this.rejectOverlap(em, quote, { id: row.id, ...merged }, scope)
+      em.assign(row, { ...this.values(merged), updatedByUserId: actor, updatedAt: new Date() })
+      return this.save(em, quote, row, before, scope, true)
+    })
+  }
+
+  async remove(quoteId: string, id: string, actor: string, scope: TenantScope, expectedRevision?: number): Promise<AdjustmentWriteResult> {
+    await this.requireEnabled(scope)
+    return this.write(quoteId, scope, expectedRevision, async (em, quote) => {
+      const row = await this.loadRow(em, quote.id, id, scope)
+      const preview = await this.deps.quotingService.recalculateLockedQuote(em, quote, scope, false)
+      const invalid = preview.adjustmentErrors?.some((error) => error.adjustmentId === id) ?? false
+      await this.assertMutable(em, quote, scope, invalid)
+      const before = adjustmentSnapshot(row)
+      row.deletedAt = new Date(); row.isActive = false; row.updatedByUserId = actor; row.updatedAt = new Date()
+      return this.save(em, quote, row, before, scope, false)
+    })
+  }
+
+  /** Restores an audited previous row under the same quote lock; never reopens a locked quote. */
+  async undo(quoteId: string, id: string, before: AdjustmentSnapshot | null, after: AdjustmentSnapshot, actor: string, scope: TenantScope): Promise<void> {
+    await this.requireEnabled(scope)
+    await this.write(quoteId, scope, undefined, async (em, quote) => {
+      await this.assertMutable(em, quote, scope)
+      for (const snapshot of [before, after]) {
+        if (snapshot && (snapshot.tenantId !== scope.tenantId || snapshot.organizationId !== scope.organizationId || snapshot.quoteConfigurationId !== quote.id || snapshot.id !== id)) {
+          throw new QuotingError(403, 'Adjustment undo scope mismatch')
+        }
+      }
+      const row = await this.loadRow(em, quote.id, id, scope, true)
+      if (snapshotKey(adjustmentSnapshot(row)) !== snapshotKey(after)) throw new QuotingError(409, 'Adjustment changed since this action')
+      const restored = before ? cpqPriceAdjustmentInputSchema.parse(this.inputFromSnapshot(before)) : null
+      // Restoring an active row must not create an overlap a rep added since.
+      if (restored && before?.isActive && !before.deletedAt) await this.rejectOverlap(em, quote, { id, ...restored }, scope)
+      const beforeUndo = adjustmentSnapshot(row)
+      if (before && restored) em.assign(row, { ...this.values(restored),
+        deletedAt: before.deletedAt ? new Date(before.deletedAt) : null, isActive: before.isActive, updatedByUserId: actor, updatedAt: new Date() })
+      else { row.deletedAt = new Date(); row.isActive = false; row.updatedByUserId = actor; row.updatedAt = new Date() }
+      await this.save(em, quote, row, beforeUndo, scope, false)
+    })
+  }
+
+  private inputFromSnapshot(snapshot: AdjustmentSnapshot): PriceAdjustmentInput {
+    const { id, quoteConfigurationId, quoteId, tenantId, organizationId, createdByUserId, createdAt, updatedAt, deletedAt, isActive, ...input } = snapshot
+    return input
+  }
+
+  private values(input: PriceAdjustmentInput) {
+    return { level: input.level, quoteLineId: input.quoteLineId, chargeCode: input.chargeCode ?? null,
+      chargeTypeFilter: input.chargeTypeFilter ?? null, adjustmentType: input.adjustmentType, value: String(input.value),
+      currencyCode: input.currencyCode ?? null, reasonCode: input.reasonCode, reasonNote: input.reasonNote ?? null }
+  }
+
+  private write<T>(quoteId: string, scope: TenantScope, revision: number | undefined, execute: (em: EntityManager, quote: CpqQuoteConfiguration) => Promise<T>) {
+    return withQuotePricingWrite(this.deps.em, quoteId, scope, execute, (status, message) => new QuotingError(status, message), revision, undefined, { pricingCause: 'adjustment' })
+  }
+
+  private async save(em: EntityManager, quote: CpqQuoteConfiguration, row: CpqQuotePriceAdjustment, before: AdjustmentSnapshot | null, scope: TenantScope, rejectInvalid: boolean): Promise<AdjustmentWriteResult> {
+    let priced: QuoteResult | undefined
+    await withAtomicFlush(em, [
+      () => { em.persist(row) },
+      async () => { priced = await this.deps.quotingService.recalculateLockedQuote(em, quote, scope) },
+    ])
+    if (!priced) throw new Error('Adjustment recalculation did not return a quote')
+    const invalid = priced.adjustmentErrors?.find((error) => error.adjustmentId === row.id)
+    if (rejectInvalid && invalid) throw new QuotingError(422, invalid.code, undefined, { code: invalid.code, adjustmentId: row.id })
+    return { adjustment: adjustmentSnapshot(row), before, quote: priced }
+  }
+
+  private async requireEnabled(scope: TenantScope) {
+    if (!(await this.enabled(scope.tenantId))) throw new QuotingError(403, 'Manual price adjustments are disabled')
+  }
+
+  private async requireTarget(em: EntityManager, quote: CpqQuoteConfiguration, quoteLineId: string, scope: TenantScope) {
+    const line = await findOneWithDecryption(em, CpqQuoteLineConfiguration, { quoteConfigurationId: quote.id, quoteLineId, ...scope, deletedAt: null }, undefined, scope)
+    if (!line) throw new QuotingError(404, 'Quote line not found')
+    if (!(line.offeringId || line.productId) || isArcMirrorLine(line.configuration, quote.quoteType)) throw new QuotingError(422, 'LINE_NOT_ELIGIBLE')
+  }
+
+  /**
+   * Refuse overlaps against every stored row, valid or not: an overlap hidden
+   * behind a currently-invalid row would start applying once that row is
+   * deleted, changing the price of a submitted quote. Runs before any mutation.
+   */
+  private async rejectOverlap(em: EntityManager, quote: CpqQuoteConfiguration, candidate: Parameters<typeof adjustmentsOverlap>[0], scope: TenantScope) {
+    const stored = await loadQuoteAdjustments(em, quote.id, scope)
+    if (stored.some((other) => adjustmentsOverlap(candidate, other))) {
+      throw new QuotingError(422, 'ADJUSTMENT_OVERLAP', undefined, { code: 'ADJUSTMENT_OVERLAP', adjustmentId: candidate.id })
+    }
+  }
+
+  private async requireReason(em: EntityManager, code: string, scope: TenantScope) {
+    const dictionary = await findOneWithDecryption(em, Dictionary, { key: REASON_DICTIONARY, ...scope, deletedAt: null, isActive: true }, undefined, scope)
+    const entry = dictionary && await findOneWithDecryption(em, DictionaryEntry, { dictionary: dictionary.id, ...scope, value: code }, undefined, scope)
+    if (!entry) throw new QuotingError(422, 'REASON_NOT_FOUND')
+  }
+
+  private async assertMutable(em: EntityManager, quote: CpqQuoteConfiguration, scope: TenantScope, invalidDelete = false) {
+    const order = await findOneWithDecryption(em, CpqOrderConfiguration, { sourceQuoteId: quote.id, ...scope, deletedAt: null }, undefined, scope)
+    const allowed = ADJUSTMENT_MUTABLE_STATUSES.includes(quote.cpqStatus as CpqStatus)
+    const invalidException = invalidDelete && !TERMINAL_STATUSES.includes(quote.cpqStatus as CpqStatus)
+    if (order || (!allowed && !invalidException)) throw new QuotingError(409, 'ADJUSTMENT_LOCKED')
+  }
+
+  private async loadRow(em: EntityManager, quoteConfigurationId: string, id: string, scope: TenantScope, deleted = false) {
+    const row = await findOneWithDecryption(em, CpqQuotePriceAdjustment, { id, quoteConfigurationId, ...scope, ...(deleted ? {} : { deletedAt: null, isActive: true }) }, undefined, scope)
+    if (!row) throw new QuotingError(404, 'Adjustment not found')
+    return row
+  }
+}
+
+function snapshotKey(snapshot: AdjustmentSnapshot): string {
+  return JSON.stringify(Object.entries(snapshot).sort(([left], [right]) => left.localeCompare(right)))
+}

package/src/modules/cpq/services/priceAdjustments/chargeWaterfall.ts

@@ -0,0 +1,28 @@
+import type { ResolvedCharge } from '../types'
+
+/** Normalize legacy snapshots without changing their offer, rules or tier breakdown. */
+export function withChargeWaterfall(charge: ResolvedCharge): ResolvedCharge {
+  const adjustments = charge.adjustments ?? []
+  const rules = adjustments.filter((entry) => entry.origin !== 'manual')
+  const manual = adjustments.find((entry) => entry.origin === 'manual')
+  const listUnitPrice = charge.listUnitPrice ?? rules[0]?.unitPriceBefore ?? manual?.unitPriceBefore ?? charge.unitPrice
+  const standardUnitPrice = charge.standardUnitPrice ?? rules.at(-1)?.unitPriceAfter ?? manual?.unitPriceBefore ?? charge.unitPrice
+  // Keep the exact stored total when no recalculation is needed (tier averages
+  // may not multiply back to the byte-identical stored total).
+  const totalAt = (unit: number) => charge.totalPrice === null ? null
+    : unit === charge.unitPrice ? charge.totalPrice : unit * (charge.quantity ?? 1)
+  return {
+    ...charge,
+    listUnitPrice,
+    listTotalPrice: charge.listTotalPrice !== undefined ? charge.listTotalPrice : totalAt(listUnitPrice),
+    standardUnitPrice,
+    standardTotalPrice: charge.standardTotalPrice !== undefined ? charge.standardTotalPrice : totalAt(standardUnitPrice),
+    ...(charge.adjustments ? { adjustments: adjustments.map((entry) => ({ ...entry, origin: entry.origin ?? 'rule' })) } : {}),
+  }
+}
+
+/** Keep the public calculator's default response compatible and free of waterfall data. */
+export function withoutChargeWaterfall(charge: ResolvedCharge): ResolvedCharge {
+  const { listUnitPrice, listTotalPrice, standardUnitPrice, standardTotalPrice, ...publicCharge } = charge
+  return publicCharge
+}

package/src/modules/cpq/services/priceAdjustments/loadQuoteAdjustments.ts

@@ -0,0 +1,25 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CpqQuotePriceAdjustment } from '../../data/entities'
+import { resolvedPriceAdjustmentSchema, type PriceAdjustment } from '../../data/price-adjustments'
+import type { TenantScope } from '../types'
+
+/** One aggregate load per recalculation; keyset batches avoid an unbounded query. */
+export async function loadQuoteAdjustments(em: EntityManager, quoteConfigurationId: string, scope: TenantScope): Promise<PriceAdjustment[]> {
+  const result: PriceAdjustment[] = []
+  let after: string | undefined
+  for (;;) {
+    const rows = await findWithDecryption(em, CpqQuotePriceAdjustment, {
+      quoteConfigurationId, ...scope, deletedAt: null, isActive: true,
+      ...(after ? { id: { $gt: after } } : {}),
+    }, { limit: 500, orderBy: { id: 'asc' } }, scope)
+    for (const row of rows) result.push(resolvedPriceAdjustmentSchema.parse({
+      id: row.id, level: row.level, quoteLineId: row.quoteLineId, chargeCode: row.chargeCode,
+      chargeTypeFilter: row.chargeTypeFilter, adjustmentType: row.adjustmentType, value: Number(row.value),
+      currencyCode: row.currencyCode, reasonCode: row.reasonCode, reasonNote: row.reasonNote,
+      fromMonth: row.fromMonth, toMonth: row.toMonth, windowKind: row.windowKind, createdByUserId: row.createdByUserId,
+    }))
+    if (rows.length < 500) return result
+    after = rows[rows.length - 1].id
+  }
+}

package/src/modules/cpq/services/priceAdjustments/pricingSnapshot.ts

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto'
+import type { PriceAdjustment } from '../../data/price-adjustments'
+import type { PricingWaterfallSummary, ResolvedCharge } from '../types'
+import { withChargeWaterfall } from './chargeWaterfall'
+
+export interface SnapshotLine {
+  lineId: string
+  quantity: number
+  termMonths?: number | null
+  /** ARC mirrors are excluded from deal value until their negotiated re-rate is supported. */
+  includeInDeal?: boolean
+  charges: ResolvedCharge[]
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (value !== null && typeof value === 'object') {
+    const object = value as Record<string, unknown>
+    return `{${Object.keys(object).sort().filter((key) => object[key] !== undefined).map((key) => `${JSON.stringify(key)}:${canonical(object[key])}`).join(',')}}`
+  }
+  return JSON.stringify(value ?? null)
+}
+
+/** Signed fractions: a rule surcharge yields a negative discount depth. */
+function depth(before: number, after: number): number | null {
+  return before === 0 ? null : 1 - after / before
+}
+
+export function computeWaterfallSummary(
+  lines: SnapshotLine[],
+  adjustments: PriceAdjustment[],
+  currencyCode: string,
+): PricingWaterfallSummary {
+  let listNrcTotal = 0, listMrcTotal = 0, standardNrcTotal = 0, standardMrcTotal = 0
+  let ruleDiscountTotal = 0, manualDiscountTotal = 0
+  const dealValue = { list: 0, standard: 0, offer: 0 }
+  const lineDepths: number[] = []
+  for (const line of lines) {
+    let standardDeal = 0, offerDeal = 0
+    for (const input of line.charges) {
+      const charge = withChargeWaterfall(input)
+      if (charge.chargeType === 'usage') continue
+      const list = (charge.listTotalPrice ?? 0) * line.quantity
+      const standard = (charge.standardTotalPrice ?? 0) * line.quantity
+      const offer = (charge.totalPrice ?? 0) * line.quantity
+      if (charge.chargeType === 'nrc') { listNrcTotal += list; standardNrcTotal += standard }
+      else { listMrcTotal += list; standardMrcTotal += standard }
+      for (const entry of charge.adjustments ?? []) {
+        const discount = Math.max(0, -entry.delta) * (charge.quantity ?? 1) * line.quantity
+        if (entry.origin === 'manual') manualDiscountTotal += discount
+        else ruleDiscountTotal += discount
+      }
+      if (line.includeInDeal === false) continue
+      const months = charge.chargeType === 'nrc' ? 1 : line.termMonths ?? 12
+      dealValue.list += list * months
+      dealValue.standard += standard * months
+      dealValue.offer += offer * months
+      standardDeal += standard * months; offerDeal += offer * months
+    }
+    const manualDepth = depth(standardDeal, offerDeal)
+    if (manualDepth !== null) lineDepths.push(manualDepth)
+  }
+  const pricedLines = lines.map((line) => ({
+    lineId: line.lineId, quantity: line.quantity, termMonths: line.termMonths ?? 12, includeInDeal: line.includeInDeal !== false,
+    charges: line.charges.map((input) => {
+      const charge = withChargeWaterfall(input)
+      return { chargeCode: charge.chargeCode, chargeType: charge.chargeType, currencyCode: charge.currencyCode,
+        listUnitPrice: charge.listUnitPrice, listTotalPrice: charge.listTotalPrice,
+        standardUnitPrice: charge.standardUnitPrice, standardTotalPrice: charge.standardTotalPrice,
+        unitPrice: charge.unitPrice, totalPrice: charge.totalPrice }
+    }).sort((a, b) => a.chargeCode.localeCompare(b.chargeCode) || canonical(a).localeCompare(canonical(b))),
+  })).sort((a, b) => a.lineId.localeCompare(b.lineId))
+  const pricedAdjustments = adjustments.map((row) => ({
+    id: row.id, level: row.level, quoteLineId: row.quoteLineId, chargeCode: row.chargeCode ?? null,
+    chargeTypeFilter: row.chargeTypeFilter ?? null, adjustmentType: row.adjustmentType, value: row.value,
+    currencyCode: row.currencyCode ?? null, windowKind: row.windowKind ?? 'relative', fromMonth: row.fromMonth ?? 1, toMonth: row.toMonth ?? null,
+  })).sort((a, b) => a.id.localeCompare(b.id))
+  return {
+    listNrcTotal, listMrcTotal, standardNrcTotal, standardMrcTotal,
+    ruleDiscountTotal, manualDiscountTotal, dealValue,
+    discountDepth: { rule: depth(dealValue.list, dealValue.standard), manual: depth(dealValue.standard, dealValue.offer),
+      total: depth(dealValue.list, dealValue.offer), maxLineManual: lineDepths.length ? Math.max(...lineDepths) : null },
+    hasTimeBasedAdjustments: false,
+    snapshotHash: createHash('sha256').update(canonical({ currencyCode, lines: pricedLines, adjustments: pricedAdjustments })).digest('hex'),
+  }
+}

package/src/modules/cpq/services/priceAdjustments/quoteAdjustmentLifecycle.ts

@@ -0,0 +1,68 @@
+import { randomUUID } from 'node:crypto'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import { SalesQuoteLine } from '@open-mercato/core/modules/sales/data/entities'
+import { CpqQuoteLineConfiguration, CpqQuotePriceAdjustment } from '../../data/entities'
+import type { TenantScope } from '../types'
+
+export async function cloneQuoteAdjustments(em: EntityManager, sourceId: string, target: { id: string; quoteId: string }, lineIds: Map<string, string>, scope: TenantScope): Promise<void> {
+  let after: string | undefined
+  for (;;) {
+    const rows = await findWithDecryption(em, CpqQuotePriceAdjustment, { quoteConfigurationId: sourceId, ...scope, deletedAt: null,
+      ...(after ? { id: { $gt: after } } : {}) }, { limit: 500, orderBy: { id: 'asc' } }, scope)
+    for (const row of rows) {
+      em.persist(em.create(CpqQuotePriceAdjustment, { id: randomUUID(), ...scope, quoteConfigurationId: target.id, quoteId: target.quoteId,
+        // An orphaned invalid target remains invalid, without pointing back into the source quote.
+        quoteLineId: lineIds.get(row.quoteLineId) ?? randomUUID(), level: row.level, chargeCode: row.chargeCode,
+        chargeTypeFilter: row.chargeTypeFilter, adjustmentType: row.adjustmentType, value: row.value, currencyCode: row.currencyCode,
+        windowKind: row.windowKind, fromMonth: row.fromMonth, toMonth: row.toMonth,
+        reasonCode: row.reasonCode, reasonNote: row.reasonNote, createdByUserId: row.createdByUserId, isActive: row.isActive }))
+    }
+    if (rows.length < 500) return
+    after = rows[rows.length - 1].id
+  }
+}
+
+/** Delete the complete bundle subtree and its adjustments before recalculation reads it. */
+export async function removeQuoteLineTree(em: EntityManager, quoteConfigurationId: string, root: CpqQuoteLineConfiguration, scope: TenantScope): Promise<void> {
+  const children = new Map<string, CpqQuoteLineConfiguration[]>()
+  let after: string | undefined
+  for (;;) {
+    const rows = await findWithDecryption(em, CpqQuoteLineConfiguration, { quoteConfigurationId, ...scope, deletedAt: null,
+      ...(after ? { id: { $gt: after } } : {}) }, { limit: 500, orderBy: { id: 'asc' } }, scope)
+    for (const row of rows) if (row.parentLineId) {
+      const siblings = children.get(row.parentLineId) ?? []
+      siblings.push(row); children.set(row.parentLineId, siblings)
+    }
+    if (rows.length < 500) break
+    after = rows[rows.length - 1].id
+  }
+  const selected: CpqQuoteLineConfiguration[] = [], seen = new Set<string>()
+  const queue = [root]
+  for (let index = 0; index < queue.length; index++) {
+    const line = queue[index]
+    if (seen.has(line.quoteLineId)) continue
+    seen.add(line.quoteLineId); selected.push(line); queue.push(...(children.get(line.quoteLineId) ?? []))
+  }
+  const sales: SalesQuoteLine[] = [], adjustments: CpqQuotePriceAdjustment[] = []
+  const ids = selected.map((line) => line.quoteLineId)
+  for (let index = 0; index < ids.length; index += 500) {
+    const lineIds = ids.slice(index, index + 500)
+    sales.push(...await findWithDecryption(em, SalesQuoteLine, { id: { $in: lineIds }, ...scope, deletedAt: null }, { limit: 500 }, scope))
+    let cursor: string | undefined
+    for (;;) {
+      const rows = await findWithDecryption(em, CpqQuotePriceAdjustment, { quoteConfigurationId, quoteLineId: { $in: lineIds }, ...scope, deletedAt: null,
+        ...(cursor ? { id: { $gt: cursor } } : {}) }, { limit: 500, orderBy: { id: 'asc' } }, scope)
+      adjustments.push(...rows)
+      if (rows.length < 500) break
+      cursor = rows[rows.length - 1].id
+    }
+  }
+  const now = new Date()
+  await withAtomicFlush(em, [() => {
+    for (const line of selected) line.deletedAt = now
+    for (const line of sales) line.deletedAt = now
+    for (const adjustment of adjustments) { adjustment.deletedAt = now; adjustment.isActive = false }
+  }])
+}

package/src/modules/cpq/services/priceAdjustments/quotePricingEvents.ts

@@ -0,0 +1,94 @@
+import { emitCpqEvent } from '../../events'
+import type { CpqQuoteConfiguration } from '../../data/entities'
+import type { PricingWaterfallSummary } from '../types'
+
+export type QuotePricingCause = 'adjustment' | 'line' | 'recalculate' | 'clone'
+export type QuoteStatusCause = 'manual' | 'auto'
+
+/** Describes the write so its committed effect can be named in the events. */
+export interface QuoteWriteEvents {
+  pricingCause: QuotePricingCause
+  /** `manual` only for an operator-requested transition; recalculation-driven changes are `auto`. */
+  statusCause?: QuoteStatusCause
+  actorUserId?: string | null
+}
+
+export interface QuoteEventState {
+  snapshotHash: string | null
+  cpqStatus: string
+}
+
+type SnapshotSource = Pick<CpqQuoteConfiguration, 'id' | 'cpqStatus' | 'currencyCode' | 'pricingRevision' | 'pricingSummary' | 'tenantId' | 'organizationId'>
+  & { quoteType?: string | null }
+
+export interface QuotePricingSnapshot {
+  quoteId: string
+  quoteType: 'new' | 'amend' | 'renew' | 'cancel'
+  cpqStatus: string
+  currencyCode: string
+  pricingRevision: number
+  snapshotHash: string
+  dealValue: PricingWaterfallSummary['dealValue']
+  discountDepth: PricingWaterfallSummary['discountDepth']
+  hasTimeBasedAdjustments: boolean
+}
+
+type Emit = (eventId: string, payload: Record<string, unknown>) => Promise<unknown> | unknown
+
+function storedHash(summary: Record<string, unknown> | null | undefined): string | null {
+  const hash = summary?.snapshotHash
+  return typeof hash === 'string' && hash.length > 0 ? hash : null
+}
+
+export function captureQuoteEventState(quote: Pick<CpqQuoteConfiguration, 'cpqStatus' | 'pricingSummary'>): QuoteEventState {
+  return { snapshotHash: storedHash(quote.pricingSummary), cpqStatus: quote.cpqStatus }
+}
+
+export function buildQuotePricingSnapshot(quote: SnapshotSource): QuotePricingSnapshot {
+  const summary = (quote.pricingSummary ?? {}) as Partial<PricingWaterfallSummary>
+  const quoteType = quote.quoteType === 'amend' || quote.quoteType === 'renew' || quote.quoteType === 'cancel' ? quote.quoteType : 'new'
+  return {
+    quoteId: quote.id,
+    quoteType,
+    cpqStatus: quote.cpqStatus,
+    currencyCode: quote.currencyCode,
+    pricingRevision: quote.pricingRevision ?? 0,
+    snapshotHash: storedHash(quote.pricingSummary) ?? '',
+    dealValue: summary.dealValue ?? { list: 0, standard: 0, offer: 0 },
+    discountDepth: summary.discountDepth ?? { rule: null, manual: null, total: null, maxLineManual: null },
+    hasTimeBasedAdjustments: summary.hasTimeBasedAdjustments === true,
+  }
+}
+
+/**
+ * Emits the committed effect of one quote write. Call only after the
+ * transaction has committed. A null previous hash is a legacy quote's first
+ * baseline and never counts as a pricing change. Dispatch failures are logged
+ * and swallowed: the write stands and the stored hash stays authoritative.
+ */
+export async function emitQuoteWriteEvents(
+  before: QuoteEventState | null,
+  quote: SnapshotSource,
+  options: QuoteWriteEvents,
+  emit: Emit = emitCpqEvent as unknown as Emit,
+): Promise<void> {
+  const after = captureQuoteEventState(quote)
+  const base = { tenantId: quote.tenantId, organizationId: quote.organizationId, ...buildQuotePricingSnapshot(quote), occurredAt: new Date().toISOString() }
+  const pricingChanged = after.snapshotHash !== null
+    && (before === null ? true : before.snapshotHash !== null && before.snapshotHash !== after.snapshotHash)
+  const pending: Array<[string, Record<string, unknown>]> = []
+  if (pricingChanged) pending.push(['cpq.quote.pricing_changed', { ...base, cause: options.pricingCause }])
+  if (before !== null && before.cpqStatus !== after.cpqStatus) {
+    pending.push(['cpq.quote.status_changed', {
+      ...base, fromStatus: before.cpqStatus, toStatus: after.cpqStatus,
+      cause: options.statusCause ?? 'auto', actorUserId: options.actorUserId ?? null,
+    }])
+  }
+  for (const [eventId, payload] of pending) {
+    try {
+      await emit(eventId, payload)
+    } catch (error) {
+      console.error(`[cpq] failed to emit ${eventId} for quote ${quote.id}`, error)
+    }
+  }
+}

package/src/modules/cpq/services/priceAdjustments/quotePricingWrite.ts

@@ -0,0 +1,51 @@
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import { LockMode } from '@mikro-orm/core'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CpqQuoteConfiguration } from '../../data/entities'
+import type { TenantScope } from '../types'
+import { captureQuoteEventState, emitQuoteWriteEvents, type QuoteEventState, type QuoteWriteEvents } from './quotePricingEvents'
+
+/** Every pricing write and conversion locks the same scoped aggregate row. */
+export async function withQuotePricingWrite<T>(
+  em: EntityManager,
+  quoteId: string,
+  scope: TenantScope,
+  execute: (transaction: EntityManager, quote: CpqQuoteConfiguration) => Promise<T>,
+  makeError: (status: number, message: string) => Error,
+  expectedRevision?: number,
+  validate?: (quote: CpqQuoteConfiguration) => void,
+  events: QuoteWriteEvents = { pricingCause: 'recalculate' },
+): Promise<T> {
+  // Do not inherit managed objects/pending writes or propagate committed state
+  // back into the caller's identity map. The returned DTO is authoritative;
+  // callers that need fresh entities must reload them in their own context.
+  // The isolated fork opens its own connection. Called from inside another
+  // transaction it could not see that transaction's uncommitted quote, and it
+  // would block forever on a row lock that transaction holds — fail fast.
+  if (em.isInTransaction?.()) throw new Error('withQuotePricingWrite must not run inside an existing transaction')
+  const isolated = em.fork({ clear: true, useContext: false })
+  const committed: { quote?: CpqQuoteConfiguration; before?: QuoteEventState } = {}
+  const result = await isolated.transactional(async (transaction) => {
+    const scoped = { organizationId: scope.organizationId, tenantId: scope.tenantId, deletedAt: null }
+    const options = { lockMode: LockMode.PESSIMISTIC_WRITE, refresh: true }
+    const quote = await findOneWithDecryption(transaction, CpqQuoteConfiguration, { ...scoped, id: quoteId }, options, scope)
+      ?? await findOneWithDecryption(transaction, CpqQuoteConfiguration, { ...scoped, quoteId }, options, scope)
+    if (!quote) throw makeError(404, 'Quote not found')
+    const revision = quote.pricingRevision ?? 0
+    if (expectedRevision !== undefined && expectedRevision !== revision) throw makeError(409, 'STALE_REVISION')
+    validate?.(quote)
+    committed.quote = quote
+    committed.before = captureQuoteEventState(quote)
+    // This scalar update and every later flush are inside the same DB transaction.
+    let written!: T
+    await withAtomicFlush(transaction, [
+      () => { quote.pricingRevision = revision + 1 },
+      async () => { written = await execute(transaction, quote) },
+    ])
+    return written
+  }, { clear: true })
+  // `transactional` resolved, so the write is committed; a rolled-back write never reaches here.
+  if (committed.quote && committed.before) await emitQuoteWriteEvents(committed.before, committed.quote, events)
+  return result
+}