@dainamite/cpq 0.5.0 → 0.7.0

package/src/modules/cpq/services/__tests__/quoteDetachTargetAdjustments.test.ts

@@ -0,0 +1,54 @@
+import { randomUUID } from 'node:crypto'
+import { DefaultCpqQuotingService } from '../cpqQuotingService'
+import { CpqQuoteConfiguration, CpqQuoteLineConfiguration, CpqQuotePriceAdjustment, CpqQuoteTargetSubscription } from '../../data/entities'
+import { SalesQuote, SalesQuoteLine } from '@open-mercato/core/modules/sales/data/entities'
+
+jest.mock('../../events', () => ({ emitCpqEvent: jest.fn().mockResolvedValue(undefined) }))
+const scope = { tenantId: randomUUID(), organizationId: randomUUID() }
+
+it('detaching an ARC target removes its lines and their adjustments under the pricing lock', async () => {
+  const quoteId = randomUUID(), salesId = randomUUID(), lineId = randomUUID(), childId = randomUUID(), subscriptionId = randomUUID()
+  const quote = { id: quoteId, quoteId: salesId, customerId: randomUUID(), cpqStatus: 'ready', quoteType: 'amend', version: 1, pricingRevision: 4, currencyCode: 'USD', ...scope }
+  const line = { id: randomUUID(), quoteLineId: lineId, quoteConfigurationId: quoteId, offeringId: 'offer', parentLineId: null, targetSubscriptionId: subscriptionId, quantity: 1, configuration: {}, charges: [], deletedAt: null as Date | null, ...scope }
+  const child = { ...line, id: randomUUID(), quoteLineId: childId, parentLineId: lineId, targetSubscriptionId: null }
+  const adjustment = { id: randomUUID(), quoteConfigurationId: quoteId, quoteLineId: childId, deletedAt: null as Date | null, isActive: true, ...scope }
+  const target = { id: randomUUID(), quoteId, subscriptionId, quoteType: 'amend', deletedAt: null as Date | null, ...scope }
+  const salesLine = { id: lineId, deletedAt: null as Date | null, ...scope }
+  const rows = new Map<unknown, Array<Record<string, unknown>>>([
+    [CpqQuoteConfiguration, [quote]], [CpqQuoteLineConfiguration, [line, child]], [CpqQuotePriceAdjustment, [adjustment]],
+    [CpqQuoteTargetSubscription, [target]], [SalesQuote, [{ id: salesId, quoteNumber: 'Q-1', currencyCode: 'USD', ...scope }]], [SalesQuoteLine, [salesLine]],
+  ])
+  const matches = (row: Record<string, unknown>, where: Record<string, unknown>) => Object.entries(where).every(([key, value]) =>
+    value === null ? row[key] == null : typeof value === 'object' ? true : row[key] === value)
+  const em = {
+    fork: jest.fn(), transactional: jest.fn(), persist: jest.fn(), flush: jest.fn().mockResolvedValue(undefined),
+    assign: jest.fn((entity: object, values: object) => Object.assign(entity, values)),
+    findOne: jest.fn(async (entity: unknown, where: Record<string, unknown>) => (rows.get(entity) ?? []).find((row) => matches(row, where)) ?? null),
+    find: jest.fn(async (entity: unknown, where: Record<string, unknown>) => (rows.get(entity) ?? []).filter((row) => matches(row, where))),
+  }
+  em.fork.mockReturnValue(em)
+  em.transactional.mockImplementation(async (execute: (tx: typeof em) => Promise<unknown>) => execute(em))
+  const service = new DefaultCpqQuotingService({ em: em as never,
+    cpqPricingService: { resolveProductCharges: async () => [] } as never,
+    cpqValidationService: { validateOfferingConfiguration: async () => ({ errors: [] }), validateRelationships: async () => [] } as never,
+    cpqProductService: {} as never, salesDocumentNumberGenerator: {} as never })
+
+  await expect(service.detachTargetSubscription(quoteId, target.id, scope)).resolves.toEqual({ ok: true })
+  expect(em.transactional).toHaveBeenCalledTimes(1)
+  expect(quote.pricingRevision).toBe(5)
+  expect(target.deletedAt).toBeInstanceOf(Date)
+  expect(line.deletedAt).toBeInstanceOf(Date)
+  expect(child.deletedAt).toBeInstanceOf(Date)
+  expect(salesLine.deletedAt).toBeInstanceOf(Date)
+  expect(adjustment).toMatchObject({ isActive: false, deletedAt: expect.any(Date) })
+})
+
+it('refuses to detach on a submitted quote before changing anything', async () => {
+  const quote = { id: randomUUID(), quoteId: randomUUID(), cpqStatus: 'in_approval', pricingRevision: 1, ...scope }
+  const em = { fork: jest.fn(), flush: jest.fn(), find: jest.fn(), findOne: jest.fn().mockResolvedValue(quote), transactional: jest.fn() }
+  em.fork.mockReturnValue(em)
+  em.transactional.mockImplementation(async (execute: (tx: typeof em) => Promise<unknown>) => execute(em))
+  const service = new DefaultCpqQuotingService({ em: em as never, cpqPricingService: {} as never, cpqValidationService: {} as never, cpqProductService: {} as never, salesDocumentNumberGenerator: {} as never })
+  await expect(service.detachTargetSubscription(quote.id, randomUUID(), scope)).rejects.toMatchObject({ status: 409 })
+  expect(em.find).not.toHaveBeenCalled()
+})

package/src/modules/cpq/services/__tests__/quoteEventsService.test.ts

@@ -0,0 +1,72 @@
+import { DefaultCpqQuotingService } from '../cpqQuotingService'
+import { emitCpqEvent as emitImport } from '../../events'
+import { CpqProductOffering, CpqQuoteConfiguration, CpqQuoteLineConfiguration, CpqQuotePriceAdjustment } from '../../data/entities'
+import { SalesQuote, SalesQuoteLine } from '@open-mercato/core/modules/sales/data/entities'
+
+jest.mock('../../events', () => ({ emitCpqEvent: jest.fn().mockResolvedValue(undefined) }))
+const emit = emitImport as unknown as jest.Mock
+const scope = { tenantId: '11111111-1111-4111-8111-111111111111', organizationId: '22222222-2222-4222-8222-222222222222' }
+const ids = { quote: '33333333-3333-4333-8333-333333333333', sales: '44444444-4444-4444-8444-444444444444', line: '55555555-5555-4555-8555-555555555555', adjustment: '66666666-6666-4666-8666-666666666666' }
+
+function setup(pricingSummary?: Record<string, unknown>) {
+  const quote: Record<string, unknown> = { id: ids.quote, quoteId: ids.sales, customerId: 'customer', quoteType: 'new', cpqStatus: 'new', currencyCode: 'USD', pricingRevision: 0, ...scope }
+  if (pricingSummary) quote.pricingSummary = pricingSummary
+  const line = { id: 'config', quoteLineId: ids.line, quoteConfigurationId: ids.quote, offeringId: 'offer', productId: null, parentLineId: null, quantity: 1, configuration: {}, nrcTotal: '0', mrcTotal: '100', isConfigured: true, charges: [], usageEstimates: null, ...scope }
+  const row = { id: ids.adjustment, quoteConfigurationId: ids.quote, quoteId: ids.sales, quoteLineId: ids.line, level: 'charge', chargeCode: 'fee', chargeTypeFilter: null, adjustmentType: 'discount_absolute', value: '20', currencyCode: 'USD', reasonCode: 'competitive_match', reasonNote: null as string | null, windowKind: 'relative', fromMonth: 1, toMonth: null, createdByUserId: '77777777-7777-4777-8777-777777777777', ...scope }
+  const findOne = jest.fn(async (entity: unknown) => entity === CpqQuoteConfiguration ? quote : entity === SalesQuote ? { id: ids.sales, quoteNumber: 'Q-1', currencyCode: 'USD' } : entity === CpqProductOffering ? { id: 'offer', name: 'Offering', offeringType: 'simple' } : entity === SalesQuoteLine ? { id: ids.line, totalNetAmount: '100' } : null)
+  const find = jest.fn(async (entity: unknown) => entity === CpqQuoteLineConfiguration ? [line] : entity === CpqQuotePriceAdjustment ? [row] : [])
+  const tx = { findOne, find, assign: jest.fn((entity: object, updates: object) => Object.assign(entity, updates)), flush: jest.fn().mockResolvedValue(undefined) }
+  const em = { ...tx, fork: jest.fn(), transactional: jest.fn(async (execute: (manager: typeof tx) => Promise<unknown>) => execute(tx)) }
+  em.fork.mockReturnValue(em)
+  const pricing = { resolveProductCharges: jest.fn().mockResolvedValue([{ chargeCode: 'fee', chargeName: 'Fee', chargeType: 'mrc', pricingMethod: 'flat', unitPrice: 100, totalPrice: 100, quantity: 1, currencyCode: 'USD', adjustments: [] }]) }
+  const service = new DefaultCpqQuotingService({ em: em as never, cpqPricingService: pricing as never, cpqValidationService: { validateOfferingConfiguration: async () => ({ errors: [] }), validateRelationships: async () => [] } as never, cpqProductService: {} as never, salesDocumentNumberGenerator: {} as never })
+  return { service, quote, row }
+}
+const calls = (id: string) => emit.mock.calls.filter(([eventId]) => eventId === id).map(([, payload]) => payload)
+
+beforeEach(() => emit.mockClear())
+
+it('legacy quote: first save stores the baseline hash without a pricing signal, then a no-op save emits nothing', async () => {
+  const { service, quote } = setup({ nrcTotal: 0, mrcTotal: 80, usageCharges: [], usageTotalEstimated: null, discountTotal: 0, surchargeTotal: 0, currencyCode: 'USD' })
+  quote.cpqStatus = 'ready'
+  await service.recalculate(ids.quote, { save: true }, scope)
+  expect((quote.pricingSummary as Record<string, unknown>).snapshotHash).toEqual(expect.any(String))
+  expect(emit).not.toHaveBeenCalled()
+  await service.recalculate(ids.quote, { save: true }, scope)
+  expect(emit).not.toHaveBeenCalled()
+})
+
+it('emits exactly one pricing_changed per save that changes prices, and an auto status_changed', async () => {
+  const { service, row } = setup({ snapshotHash: 'empty-baseline' })
+  await service.recalculate(ids.quote, { save: true }, scope)
+  expect(calls('cpq.quote.pricing_changed')).toHaveLength(1)
+  expect(calls('cpq.quote.status_changed')).toEqual([expect.objectContaining({ fromStatus: 'new', toStatus: 'ready', cause: 'auto', actorUserId: null })])
+  emit.mockClear()
+  row.value = '30'
+  await service.recalculate(ids.quote, { save: true }, scope)
+  expect(calls('cpq.quote.pricing_changed')).toEqual([expect.objectContaining({ cause: 'recalculate', dealValue: expect.objectContaining({ offer: 70 * 12 }) })])
+  expect(calls('cpq.quote.status_changed')).toHaveLength(0)
+})
+
+it('reason edits do not change the hash, so no pricing signal', async () => {
+  const { service, row } = setup({ snapshotHash: 'empty-baseline' })
+  await service.recalculate(ids.quote, { save: true }, scope)
+  emit.mockClear()
+  row.reasonCode = 'other'; row.reasonNote = 'changed'
+  await service.recalculate(ids.quote, { save: true }, scope)
+  expect(emit).not.toHaveBeenCalled()
+})
+
+it('a read-only recalculation emits nothing', async () => {
+  const { service } = setup({ snapshotHash: 'empty-baseline' })
+  await service.recalculate(ids.quote, { save: false }, scope)
+  expect(emit).not.toHaveBeenCalled()
+})
+
+it('a manual transition emits status_changed with the actor', async () => {
+  const { service, quote } = setup({ snapshotHash: 'h' })
+  quote.cpqStatus = 'ready'
+  await service.transitionStatus(ids.quote, 'in_approval', scope, 'user-9')
+  expect(calls('cpq.quote.pricing_changed')).toHaveLength(0)
+  expect(calls('cpq.quote.status_changed')).toEqual([expect.objectContaining({ fromStatus: 'ready', toStatus: 'in_approval', cause: 'manual', actorUserId: 'user-9', snapshotHash: 'h' })])
+})

package/src/modules/cpq/services/__tests__/quotePricingEvents.test.ts

@@ -0,0 +1,126 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { emitCpqEvent as emitCpqEventImport } from '../../events'
+import { captureQuoteEventState, emitQuoteWriteEvents } from '../priceAdjustments/quotePricingEvents'
+import { withQuotePricingWrite } from '../priceAdjustments/quotePricingWrite'
+
+jest.mock('../../events', () => ({ emitCpqEvent: jest.fn().mockResolvedValue(undefined) }))
+const emitCpqEvent = emitCpqEventImport as unknown as jest.Mock
+
+const scope = { tenantId: 'tenant', organizationId: 'org' }
+const error = (status: number, message: string) => Object.assign(new Error(message), { status })
+
+function quote(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'cfg-1', quoteId: 'sales-1', tenantId: 'tenant', organizationId: 'org', cpqStatus: 'ready', quoteType: 'new',
+    currencyCode: 'USD', pricingRevision: 3,
+    pricingSummary: {
+      snapshotHash: 'hash-a', dealValue: { list: 1200, standard: 1000, offer: 800 },
+      discountDepth: { rule: 1 / 6, manual: 0.2, total: 1 / 3, maxLineManual: 0.2 }, hasTimeBasedAdjustments: false,
+    } as Record<string, unknown>,
+    ...overrides,
+  }
+}
+
+function writeHarness(locked: ReturnType<typeof quote>) {
+  const transaction = { findOne: jest.fn().mockResolvedValue(locked), flush: jest.fn().mockResolvedValue(undefined) }
+  const isolated = { transactional: jest.fn().mockImplementation(async (fn: (em: typeof transaction) => Promise<unknown>) => fn(transaction)) }
+  return { em: { fork: jest.fn().mockReturnValue(isolated) } as unknown as EntityManager, isolated }
+}
+
+const emitted = () => emitCpqEvent.mock.calls.map(([id]) => id)
+
+beforeEach(() => emitCpqEvent.mockClear())
+
+describe('emitQuoteWriteEvents', () => {
+  it('emits one pricing_changed with the pricing snapshot when the stored hash changes', async () => {
+    const q = quote()
+    const before = captureQuoteEventState({ ...q, pricingSummary: { snapshotHash: 'hash-0' } })
+    await emitQuoteWriteEvents(before, q, { pricingCause: 'adjustment' }, emitCpqEvent)
+    expect(emitCpqEvent).toHaveBeenCalledTimes(1)
+    expect(emitCpqEvent).toHaveBeenCalledWith('cpq.quote.pricing_changed', expect.objectContaining({
+      tenantId: 'tenant', organizationId: 'org', quoteId: 'cfg-1', quoteType: 'new', cpqStatus: 'ready',
+      currencyCode: 'USD', pricingRevision: 3, snapshotHash: 'hash-a',
+      dealValue: { list: 1200, standard: 1000, offer: 800 },
+      discountDepth: expect.objectContaining({ manual: 0.2 }), hasTimeBasedAdjustments: false,
+      cause: 'adjustment', occurredAt: expect.any(String),
+    }))
+  })
+
+  it('emits nothing for an unchanged hash and status (no-op recalculation, reason edit)', async () => {
+    const q = quote()
+    await emitQuoteWriteEvents(captureQuoteEventState(q), q, { pricingCause: 'recalculate' }, emitCpqEvent)
+    expect(emitCpqEvent).not.toHaveBeenCalled()
+  })
+
+  it('stores a legacy baseline without a pricing signal', async () => {
+    const q = quote()
+    await emitQuoteWriteEvents({ snapshotHash: null, cpqStatus: 'ready' }, q, { pricingCause: 'recalculate' }, emitCpqEvent)
+    expect(emitCpqEvent).not.toHaveBeenCalled()
+  })
+
+  it('emits status_changed with cause auto for a recalculation-driven transition', async () => {
+    const q = quote({ cpqStatus: 'incomplete' })
+    await emitQuoteWriteEvents({ snapshotHash: 'hash-a', cpqStatus: 'ready' }, q, { pricingCause: 'line' }, emitCpqEvent)
+    expect(emitted()).toEqual(['cpq.quote.status_changed'])
+    expect(emitCpqEvent.mock.calls[0][1]).toMatchObject({ fromStatus: 'ready', toStatus: 'incomplete', cause: 'auto', actorUserId: null })
+  })
+
+  it('emits both signals and carries the actor for a manual transition', async () => {
+    const q = quote({ cpqStatus: 'in_approval' })
+    await emitQuoteWriteEvents({ snapshotHash: 'hash-0', cpqStatus: 'ready' }, q,
+      { pricingCause: 'recalculate', statusCause: 'manual', actorUserId: 'user-1' }, emitCpqEvent)
+    expect(emitted()).toEqual(['cpq.quote.pricing_changed', 'cpq.quote.status_changed'])
+    expect(emitCpqEvent.mock.calls[1][1]).toMatchObject({ cause: 'manual', actorUserId: 'user-1', toStatus: 'in_approval' })
+  })
+
+  it('treats a new aggregate (clone) as a pricing change', async () => {
+    await emitQuoteWriteEvents(null, quote(), { pricingCause: 'clone' }, emitCpqEvent)
+    expect(emitted()).toEqual(['cpq.quote.pricing_changed'])
+    expect(emitCpqEvent.mock.calls[0][1]).toMatchObject({ cause: 'clone' })
+  })
+
+  it('logs and swallows a dispatch failure so the committed write stands', async () => {
+    const failing = jest.fn().mockRejectedValue(new Error('bus down'))
+    const log = jest.spyOn(console, 'error').mockImplementation(() => undefined)
+    await expect(emitQuoteWriteEvents({ snapshotHash: 'x', cpqStatus: 'new' }, quote(), { pricingCause: 'line' }, failing)).resolves.toBeUndefined()
+    expect(failing).toHaveBeenCalledTimes(2)
+    expect(log).toHaveBeenCalled()
+    log.mockRestore()
+  })
+})
+
+describe('withQuotePricingWrite events', () => {
+  it('emits after the transaction resolves, with the committed state', async () => {
+    const locked = quote({ pricingSummary: { snapshotHash: 'hash-0' } })
+    const { em, isolated } = writeHarness(locked)
+    let committed = false
+    isolated.transactional.mockImplementation(async (fn: (em: unknown) => Promise<unknown>) => {
+      const value = await fn({ findOne: jest.fn().mockResolvedValue(locked), flush: jest.fn() })
+      expect(emitCpqEvent).not.toHaveBeenCalled()
+      committed = true
+      return value
+    })
+    await withQuotePricingWrite(em, 'cfg-1', scope, async (_tx, q) => {
+      q.pricingSummary = { ...quote().pricingSummary }
+      return 'ok'
+    }, error, undefined, undefined, { pricingCause: 'adjustment' })
+    expect(committed).toBe(true)
+    expect(emitted()).toEqual(['cpq.quote.pricing_changed'])
+    expect(emitCpqEvent.mock.calls[0][1]).toMatchObject({ cause: 'adjustment', pricingRevision: 4 })
+  })
+
+  it('emits nothing when the write throws (rolled back)', async () => {
+    const { em } = writeHarness(quote())
+    await expect(withQuotePricingWrite(em, 'cfg-1', scope, async (_tx, q) => {
+      q.cpqStatus = 'in_approval'
+      throw new Error('boom')
+    }, error)).rejects.toThrow('boom')
+    expect(emitCpqEvent).not.toHaveBeenCalled()
+  })
+
+  it('emits nothing for a refused stale revision', async () => {
+    const { em } = writeHarness(quote())
+    await expect(withQuotePricingWrite(em, 'cfg-1', scope, async () => 'never', error, 1)).rejects.toMatchObject({ status: 409 })
+    expect(emitCpqEvent).not.toHaveBeenCalled()
+  })
+})

package/src/modules/cpq/services/__tests__/quotePricingIsolation.test.ts

@@ -0,0 +1,52 @@
+import 'reflect-metadata'
+import { MikroORM, type EntityManager } from '@mikro-orm/postgresql'
+import { ReflectMetadataProvider } from '@mikro-orm/decorators/legacy'
+import { CpqQuoteConfiguration, CpqQuoteLineConfiguration } from '../../data/entities'
+import { withQuotePricingWrite } from '../priceAdjustments/quotePricingWrite'
+
+/** Real identity maps, no database: only transaction SQL/reads are stubbed. */
+it.each([false, true])('keeps preloaded parent entities and pending writes isolated (failure=%s)', async (fail) => {
+  const orm = await MikroORM.init({ entities: [CpqQuoteConfiguration, CpqQuoteLineConfiguration],
+    dbName: 'cpq_isolation_probe', metadataProvider: ReflectMetadataProvider })
+  const parent = orm.em.fork({ clear: true })
+  const scope = { tenantId: '11111111-1111-4111-8111-111111111111', organizationId: '22222222-2222-4222-8222-222222222222' }
+  const quoteId = '33333333-3333-4333-8333-333333333333'
+  const lineId = '44444444-4444-4444-8444-444444444444'
+  const quote = parent.create(CpqQuoteConfiguration, { id: quoteId, quoteId, customerId: quoteId, ...scope, pricingRevision: 4 })
+  const line = parent.create(CpqQuoteLineConfiguration, { id: lineId, quoteLineId: lineId, quoteConfigurationId: quoteId, ...scope, mrcTotal: '100' })
+  parent.persist([quote, line])
+  const originalFork = parent.fork.bind(parent)
+  let isolated: EntityManager | undefined
+  jest.spyOn(parent, 'fork').mockImplementation((options) => {
+    const fork = originalFork(options)
+    isolated = fork
+    expect(fork.getUnitOfWork().getIdentityMap().keys()).toEqual([])
+    expect(fork.getUnitOfWork().getPersistStack().size).toBe(0)
+    // Don't run SQL: execute against this real, newly forked identity map.
+    jest.spyOn(fork, 'transactional').mockImplementation(async (execute) => execute(fork))
+    jest.spyOn(fork, 'findOne').mockImplementation(async () => {
+      const loaded = fork.getReference(CpqQuoteConfiguration, quoteId)
+      Object.assign(loaded, { ...scope, quoteId, pricingRevision: 4 })
+      return loaded as never
+    })
+    jest.spyOn(fork, 'flush').mockResolvedValue(undefined)
+    return fork
+  })
+  try {
+    const operation = withQuotePricingWrite(parent, quoteId, scope, async (transaction, locked) => {
+      expect(transaction).toBe(isolated)
+      expect(locked).not.toBe(quote)
+      const loadedLine = transaction.getReference(CpqQuoteLineConfiguration, lineId)
+      expect(loadedLine).not.toBe(line)
+      loadedLine.mrcTotal = '80'
+      if (fail) throw new Error('Rejected after repricing')
+      return locked.pricingRevision
+    }, (status, message) => Object.assign(new Error(message), { status }))
+    if (fail) await expect(operation).rejects.toThrow('Rejected after repricing')
+    else expect(await operation).toBe(5)
+    expect(quote.pricingRevision).toBe(4)
+    expect(line.mrcTotal).toBe('100')
+    expect(parent.getUnitOfWork().getPersistStack().has(quote)).toBe(true)
+    expect(parent.getUnitOfWork().getPersistStack().has(line)).toBe(true)
+  } finally { await orm.close(true) }
+})

package/src/modules/cpq/services/__tests__/quotePricingWrite.test.ts

@@ -0,0 +1,74 @@
+import { LockMode } from '@mikro-orm/core'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CpqQuoteConfiguration } from '../../data/entities'
+import { withQuotePricingWrite } from '../priceAdjustments/quotePricingWrite'
+import { QuotingError } from '../cpqQuotingService'
+const scope = { tenantId: 'tenant', organizationId: 'org' }
+const error = (status: number, message: string) => new QuotingError(status, message)
+function setup() {
+  const quote = { id: 'quote', quoteId: 'sales', pricingRevision: 4 }
+  const transaction = { findOne: jest.fn().mockResolvedValue(quote), flush: jest.fn().mockResolvedValue(undefined) }
+  const isolated = { transactional: jest.fn().mockImplementation(async (fn: (em: typeof transaction) => Promise<unknown>) => fn(transaction)) }
+  const root = { fork: jest.fn().mockReturnValue(isolated), transactional: jest.fn(), findOne: jest.fn(), flush: jest.fn() }
+  return { quote, transaction, root, isolated, em: root as unknown as EntityManager }
+}
+it('locks and refreshes the tenant-scoped root and passes only the transaction EM to the write', async () => {
+  const { quote, transaction, root, isolated, em } = setup()
+  const result = await withQuotePricingWrite(em, 'quote', scope, async (tx, locked) => {
+    expect(tx).toBe(transaction)
+    expect(locked).toBe(quote)
+    expect(locked.pricingRevision).toBe(5)
+    await tx.flush()
+    return 'saved'
+  }, error, 4)
+  expect(result).toBe('saved')
+  expect(root.fork).toHaveBeenCalledWith({ clear: true, useContext: false })
+  expect(root.transactional).not.toHaveBeenCalled()
+  expect(isolated.transactional).toHaveBeenCalledWith(expect.any(Function), { clear: true })
+  expect(transaction.findOne).toHaveBeenCalledWith(CpqQuoteConfiguration,
+    { id: 'quote', tenantId: 'tenant', organizationId: 'org', deletedAt: null },
+    { lockMode: LockMode.PESSIMISTIC_WRITE, refresh: true })
+  expect(root.findOne).not.toHaveBeenCalled()
+  expect(root.flush).not.toHaveBeenCalled()
+  expect(quote.pricingRevision).toBe(5)
+})
+it('refuses a stale revision before calling the mutation or flushing', async () => {
+  const { quote, transaction, em } = setup()
+  const write = jest.fn()
+  await expect(withQuotePricingWrite(em, 'quote', scope, write, error, 3)).rejects.toMatchObject({ status: 409, message: 'STALE_REVISION' })
+  expect(write).not.toHaveBeenCalled()
+  expect(transaction.flush).not.toHaveBeenCalled()
+  expect(quote.pricingRevision).toBe(4)
+})
+it('locks the sales quote alias with the same scope when the CPQ id lookup misses', async () => {
+  const { quote, transaction, em } = setup()
+  transaction.findOne.mockResolvedValueOnce(null)
+  await withQuotePricingWrite(em, 'sales', scope, async () => 'saved', error)
+  expect(transaction.findOne).toHaveBeenLastCalledWith(CpqQuoteConfiguration,
+    { quoteId: 'sales', ...scope, deletedAt: null }, { lockMode: LockMode.PESSIMISTIC_WRITE, refresh: true })
+  expect(quote.pricingRevision).toBe(5)
+})
+it('does not execute an out-of-scope or missing quote', async () => {
+  const { transaction, em } = setup()
+  transaction.findOne.mockResolvedValue(null)
+  const write = jest.fn()
+  await expect(withQuotePricingWrite(em, 'missing', scope, write, error)).rejects.toMatchObject({ status: 404 })
+  expect(write).not.toHaveBeenCalled()
+})
+it('propagates a write failure out of transactional so the database rolls back', async () => {
+  const { transaction, isolated, em } = setup()
+  const failure = new Error('Failed during reprice')
+  await expect(withQuotePricingWrite(em, 'quote', scope, async () => { throw failure }, error)).rejects.toBe(failure)
+  expect(isolated.transactional).toHaveBeenCalledTimes(1)
+  // The revision is flushed before a dependent query can reset its change set;
+  // the thrown error still rolls this SQL back in the real transaction.
+  expect(transaction.flush).toHaveBeenCalledTimes(1)
+})
+it('refuses to run inside an ambient transaction instead of deadlocking on its own lock', async () => {
+  const { root, em } = setup()
+  Object.assign(root, { isInTransaction: () => true })
+  const write = jest.fn()
+  await expect(withQuotePricingWrite(em, 'quote', scope, write, error)).rejects.toThrow('must not run inside an existing transaction')
+  expect(root.fork).not.toHaveBeenCalled()
+  expect(write).not.toHaveBeenCalled()
+})

package/src/modules/cpq/services/__tests__/resolveManualAdjustments.test.ts

@@ -0,0 +1,90 @@
+import { resolveManualAdjustments, type AdjustmentPricingLine } from '../priceAdjustments/resolveManualAdjustments'
+import type { PriceAdjustment } from '../../data/price-adjustments'
+import type { ResolvedCharge } from '../types'
+
+const charge: ResolvedCharge = { chargeCode: 'fee', chargeName: 'Fee', chargeType: 'mrc', pricingMethod: 'per_unit', unitPrice: 25, totalPrice: 100, quantity: 4, currencyCode: 'USD' }
+const line: AdjustmentPricingLine = { lineId: 'line', parentLineId: null, enginePriced: true, mirrored: false, charges: [charge] }
+const row: PriceAdjustment = { id: 'adj', quoteLineId: 'line', level: 'charge', chargeCode: 'fee', adjustmentType: 'discount_percent', value: 20, reasonCode: 'competitive_match' }
+function price(rows: PriceAdjustment[], lines = [line]) { return resolveManualAdjustments(lines, rows, 'USD') }
+
+it.each([
+  { adjustmentType: 'discount_percent' as const, value: 20, currencyCode: undefined, cents: 8000 },
+  { adjustmentType: 'discount_absolute' as const, value: 20, currencyCode: 'USD', cents: 8000 },
+  { adjustmentType: 'discount_absolute' as const, value: 200, currencyCode: 'USD', cents: 0 },
+  { adjustmentType: 'price_override' as const, value: 20, currencyCode: 'USD', cents: 8000 },
+  { adjustmentType: 'price_override' as const, value: 0, currencyCode: 'USD', cents: 0 },
+])('applies $adjustmentType $value against standard, per charge instance', ({ cents, ...values }) => {
+  const result = price([{ ...row, ...values }])
+  expect(result.errors).toEqual([])
+  const priced = result.lines[0].charges[0]
+  expect(Math.round(priced.totalPrice! * 100)).toBe(cents)
+  expect(Math.round(priced.unitPrice * 4 * 100)).toBe(cents)
+  expect(priced).toMatchObject({ listTotalPrice: 100, standardTotalPrice: 100 })
+  expect(priced.adjustments?.[0]).toMatchObject({ origin: 'manual', adjustmentId: 'adj', unitPriceBefore: 25 })
+  expect(charge).not.toHaveProperty('adjustments')
+})
+it('uses charge above line above nearest ancestor, without compounding', () => {
+  const rows: PriceAdjustment[] = [
+    { ...row, id: 'root', quoteLineId: 'root', level: 'line', chargeCode: undefined, value: 50 },
+    { ...row, id: 'parent', quoteLineId: 'parent', level: 'line', chargeCode: undefined, value: 30 },
+    { ...row, id: 'line', level: 'line', chargeCode: undefined, value: 10 }, row,
+  ]
+  const lines = [{ ...line, lineId: 'root' }, { ...line, lineId: 'parent', parentLineId: 'root' }, { ...line, parentLineId: 'parent' }]
+  expect(price(rows, lines).lines.map((item) => item.charges[0].totalPrice)).toEqual([50, 70, 80])
+  expect(price(rows.slice(0, -1), lines).lines[2].charges[0].totalPrice).toBe(90)
+  expect(price(rows.slice(0, -2), lines).lines[2].charges[0].totalPrice).toBe(70)
+})
+it('skips an invalid charge override and falls back to a valid line discount', () => {
+  const result = price([{ ...row, adjustmentType: 'price_override', currencyCode: 'USD', value: 30 }, { ...row, id: 'line-discount', level: 'line', chargeCode: undefined, value: 10 }])
+  expect(result.errors).toEqual([expect.objectContaining({ code: 'ABOVE_STANDARD' })])
+  expect(result.lines[0].charges[0].totalPrice).toBe(90)
+})
+it.each([
+  [{ chargeCode: 'missing' }, {}, 'ADJUSTMENT_TARGET_MISSING'],
+  [{ quoteLineId: 'missing' }, {}, 'ADJUSTMENT_TARGET_MISSING'],
+  [{ currencyCode: 'EUR' }, {}, 'CURRENCY_MISMATCH'],
+  [{ adjustmentType: 'discount_absolute', currencyCode: undefined }, {}, 'CURRENCY_MISMATCH'],
+  [{ adjustmentType: 'price_override', currencyCode: 'USD' }, { pricingMethod: 'tiered' }, 'TYPE_NOT_ALLOWED'],
+  [{ adjustmentType: 'price_override', currencyCode: 'USD' }, { pricingMethod: 'volume' }, 'TYPE_NOT_ALLOWED'],
+  [{ value: 101 }, {}, 'TYPE_NOT_ALLOWED'],
+  [{}, { chargeType: 'usage', totalPrice: null, quantity: null }, 'TYPE_NOT_ALLOWED'],
+] as const)('keeps and flags invalid adjustments (%s)', (patch, chargePatch, code) => {
+  const result = price([{ ...row, ...patch }], [{ ...line, charges: [{ ...charge, ...chargePatch }] }])
+  expect(result.errors).toEqual([expect.objectContaining({ code })])
+  expect(result.lines[0].charges[0].unitPrice).toBe(charge.unitPrice)
+})
+it('rejects ambiguous charge codes and overlapping same-level discounts', () => {
+  expect(price([row], [{ ...line, charges: [charge, charge] }]).errors[0].code).toBe('TARGET_AMBIGUOUS')
+  const result = price([row, { ...row, id: 'second' }])
+  expect(result.errors).toHaveLength(2)
+  expect(result.errors.every((error) => error.code === 'ADJUSTMENT_OVERLAP')).toBe(true)
+  expect(result.lines[0].charges[0].totalPrice).toBe(100)
+})
+it('never changes mirror/free-form offers and rejects adjustments on them', () => {
+  for (const patch of [{ mirrored: true }, { enginePriced: false }]) {
+    const contracted = { ...charge, unitPrice: 20, totalPrice: 80, standardUnitPrice: 25, standardTotalPrice: 100 }
+    const result = price([row], [{ ...line, ...patch, charges: [contracted] }])
+    expect(result.errors[0].code).toBe('LINE_NOT_ELIGIBLE')
+    expect(result.lines[0].charges[0].totalPrice).toBe(80)
+  }
+})
+it('filters line discounts by charge type and never discounts usage', () => {
+  const result = price([{ ...row, level: 'line', chargeCode: undefined, chargeTypeFilter: 'mrc' }], [{ ...line, charges: [charge, { ...charge, chargeCode: 'setup', chargeType: 'nrc' }, { ...charge, chargeCode: 'usage', chargeType: 'usage', totalPrice: null, quantity: null }] }])
+  expect(result.lines[0].charges.map((item) => item.totalPrice)).toEqual([80, 100, null])
+  expect(result.errors).toEqual([])
+})
+it('is idempotent on previously adjusted charges and safely traverses a malformed parent cycle', () => {
+  const first = price([row])
+  expect(price([row], first.lines)).toEqual(first)
+  expect(price([{ ...row, level: 'line', chargeCode: undefined }], [{ ...line, parentLineId: 'line' }]).lines[0].charges[0].totalPrice).toBe(80)
+})
+it('handles zero charge quantities without division by zero', () => {
+  const result = price([{ ...row, adjustmentType: 'discount_absolute', currencyCode: 'USD' }], [{ ...line, charges: [{ ...charge, quantity: 0, totalPrice: 0 }] }])
+  expect(result.lines[0].charges[0].unitPrice).toBe(0)
+  expect(result.lines[0].charges[0].totalPrice).toBe(0)
+})
+it('skips an invalid same-level override without treating it as an overlap with a valid discount', () => {
+  const result = price([row, { ...row, id: 'invalid', adjustmentType: 'price_override', currencyCode: 'USD', value: 200 }])
+  expect(result.errors).toEqual([expect.objectContaining({ adjustmentId: 'invalid', code: 'ABOVE_STANDARD' })])
+  expect(result.lines[0].charges[0].totalPrice).toBe(80)
+})

package/src/modules/cpq/services/__tests__/storedAdjustmentFailure.test.ts

@@ -0,0 +1,9 @@
+import { storedAdjustmentFailure } from '../priceAdjustments/storedAdjustmentFailure'
+it('refuses missing charge and orphaned line targets recorded in the stored snapshot', () => {
+  expect(storedAdjustmentFailure({} as never, [{ quoteLineId: 'line', charges: [], validationErrors: [{ message: 'ADJUSTMENT_TARGET_MISSING' }] }] as never)).toEqual({ lineId: 'line', code: 'ADJUSTMENT_TARGET_MISSING' })
+  expect(storedAdjustmentFailure({ validationResult: { errors: [{ lineId: 'removed', message: 'ADJUSTMENT_TARGET_MISSING' }] } } as never, [])).toEqual({ lineId: 'removed', code: 'ADJUSTMENT_TARGET_MISSING' })
+})
+it('fails closed on malformed charge error flags without changing legacy non-adjustment validation', () => {
+  expect(storedAdjustmentFailure({} as never, [{ quoteLineId: 'line', charges: [{ adjustmentErrors: [{}] }] }] as never)).toEqual({ lineId: 'line', code: 'ADJUSTMENT_INVALID' })
+  expect(storedAdjustmentFailure({} as never, [{ quoteLineId: 'line', validationErrors: [{ message: 'Required attribute missing' }] }] as never)).toBe(null)
+})

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

@@ -0,0 +1,87 @@
+/**
+ * Removing an existing subscription item on an Amend / Renew quote.
+ *
+ * An ARC quote mirrors each live subscription item as a quote line. Activation
+ * only acts on explicit line actions — an item with no line is left untouched —
+ * so deleting a mirror line used to keep the item active on the subscription.
+ * Instead, "remove" turns the mirror line (and its mirrored components) into a
+ * `cancel` line, which activation applies by terminating the item. Lines this
+ * quote added under it are dropped. A cancelled line can be restored from the
+ * subscription item it mirrors.
+ *
+ * Cancel quotes are excluded: every line there is already a cancel line.
+ */
+
+import { isArcMirrorLine } from './arcPriceFreeze'
+
+export type ArcRemovalLine = {
+  quoteLineId: string
+  parentLineId?: string | null
+  action: string
+  configuration: Record<string, unknown> | null | undefined
+}
+
+const ITEM_REMOVAL_QUOTE_TYPES = ['amend', 'renew'] as const
+
+function supportsItemRemoval(quoteType: string | null | undefined): boolean {
+  return (ITEM_REMOVAL_QUOTE_TYPES as readonly string[]).includes(quoteType ?? '')
+}
+
+/** Whether removing this line cancels a subscription item instead of deleting the line. */
+export function removalCancelsItem(line: Pick<ArcRemovalLine, 'configuration'>, quoteType: string | null | undefined): boolean {
+  return supportsItemRemoval(quoteType) && isArcMirrorLine(line.configuration, quoteType)
+}
+
+/** A subscription item marked for removal on an Amend / Renew quote. It is not priced. */
+export function isArcCancelledLine(line: Pick<ArcRemovalLine, 'action'>, quoteType: string | null | undefined): boolean {
+  return line.action === 'cancel' && supportsItemRemoval(quoteType)
+}
+
+/** The line and every descendant, root first. */
+export function collectLineSubtree<T extends ArcRemovalLine>(root: T, lines: readonly T[]): T[] {
+  const children = new Map<string, T[]>()
+  for (const line of lines) {
+    if (!line.parentLineId) continue
+    const siblings = children.get(line.parentLineId) ?? []
+    siblings.push(line)
+    children.set(line.parentLineId, siblings)
+  }
+  const out: T[] = []
+  const seen = new Set<string>()
+  const queue: T[] = [root]
+  for (let index = 0; index < queue.length; index++) {
+    const line = queue[index]
+    if (seen.has(line.quoteLineId)) continue
+    seen.add(line.quoteLineId)
+    out.push(line)
+    queue.push(...(children.get(line.quoteLineId) ?? []))
+  }
+  return out
+}
+
+export type ArcRemovalPlan<T> = {
+  /** Mirror lines that become `cancel` lines. */
+  cancel: T[]
+  /** Roots of quote-added subtrees to delete (each deleted with its descendants). */
+  removeRoots: T[]
+}
+
+export function planArcLineRemoval<T extends ArcRemovalLine>(root: T, lines: readonly T[], quoteType: string | null | undefined): ArcRemovalPlan<T> {
+  const subtree = collectLineSubtree(root, lines)
+  const cancel = subtree.filter((line) => isArcMirrorLine(line.configuration, quoteType) && line.action !== 'cancel')
+  const remove = subtree.filter((line) => !isArcMirrorLine(line.configuration, quoteType))
+  const removeIds = new Set(remove.map((line) => line.quoteLineId))
+  const removeRoots = remove.filter((line) => !line.parentLineId || !removeIds.has(line.parentLineId))
+  return { cancel, removeRoots }
+}
+
+export type ArcRestorePlan<T> = { ok: true; restore: T[] } | { ok: false; reason: 'parent_cancelled' }
+
+/** Restore the line and its cancelled mirrored components; blocked while its parent stays cancelled. */
+export function planArcLineRestore<T extends ArcRemovalLine>(root: T, lines: readonly T[], quoteType: string | null | undefined): ArcRestorePlan<T> {
+  const parent = root.parentLineId ? lines.find((line) => line.quoteLineId === root.parentLineId) : undefined
+  if (parent && isArcCancelledLine(parent, quoteType)) return { ok: false, reason: 'parent_cancelled' }
+  const restore = collectLineSubtree(root, lines)
+    .filter((line) => isArcCancelledLine(line, quoteType) && isArcMirrorLine(line.configuration, quoteType))
+  return { ok: true, restore }
+}