@dainamite/cpq 0.2.2 → 0.3.0

package/src/modules/cpq/data/__tests__/validators.test.ts

@@ -290,8 +290,10 @@ describe('cpqProductChargeCreateSchema', () => {
     expect(result.error.issues.some((i) => i.path[0] === 'currencyCode')).toBe(true)
   })
 
-  it('V-CHG-1: rejects flat with stray pricingTableId', () => {
-    const result = cpqProductChargeCreateSchema.safeParse({ ...flatBase, pricingTableId: VALID_UUID })
+  it('V-CHG-1: rejects a fixed price with a stray pricingTableId', () => {
+    // Explicit fixed source — a pricing table is forbidden. (Legacy `flat` is
+    // now inferred as a flat *table* lookup when a table is present.)
+    const result = cpqProductChargeCreateSchema.safeParse({ ...flatBase, pricingMethod: 'fixed', pricingTableId: VALID_UUID })
     expect(result.success).toBe(false)
     if (result.success) return
     expect(result.error.issues.some((i) => i.path[0] === 'pricingTableId')).toBe(true)
@@ -335,11 +337,9 @@ describe('cpqProductChargeCreateSchema', () => {
   })
 
   // ─── Legacy `fixed` alias ──────────────────────────────────
-  it('normalises legacy `fixed` to `flat` on input', () => {
+  it('accepts the legacy `fixed` pricing method (route normalises to the split shape)', () => {
     const result = cpqProductChargeCreateSchema.safeParse({ ...flatBase, pricingMethod: 'fixed' })
     expect(result.success).toBe(true)
-    if (!result.success) return
-    expect(result.data.pricingMethod).toBe('flat')
   })
 
   it('legacy `fixed` still requires fixedPrice + currencyCode', () => {
@@ -347,6 +347,61 @@ describe('cpqProductChargeCreateSchema', () => {
     const result = cpqProductChargeCreateSchema.safeParse({ ...partial, pricingMethod: 'fixed' })
     expect(result.success).toBe(false)
   })
+
+  // ─── XD-297: charge model × pricing method combinations ──────
+  it('rejects volume + fixed (volume requires table lookup)', () => {
+    const result = cpqProductChargeCreateSchema.safeParse({ ...flatBase, chargeModel: 'volume', pricingMethod: 'fixed' })
+    expect(result.success).toBe(false)
+    if (result.success) return
+    expect(result.error.issues.some((i) => i.path[0] === 'pricingMethod')).toBe(true)
+  })
+
+  it('rejects tiered + fixed (tiered requires table lookup)', () => {
+    const result = cpqProductChargeCreateSchema.safeParse({ ...flatBase, chargeModel: 'tiered', pricingMethod: 'fixed' })
+    expect(result.success).toBe(false)
+    if (result.success) return
+    expect(result.error.issues.some((i) => i.path[0] === 'pricingMethod')).toBe(true)
+  })
+
+  it('accepts per_unit + fixed with a quantity attribute', () => {
+    const result = cpqProductChargeCreateSchema.safeParse({
+      code: 'seat', name: 'Seat', chargeType: 'mrc',
+      chargeModel: 'per_unit', pricingMethod: 'fixed',
+      fixedPrice: '5', currencyCode: 'USD', quantityAttributeCode: 'seats',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects per_unit + fixed without a quantity attribute', () => {
+    const result = cpqProductChargeCreateSchema.safeParse({
+      code: 'seat', name: 'Seat', chargeType: 'mrc',
+      chargeModel: 'per_unit', pricingMethod: 'fixed',
+      fixedPrice: '5', currencyCode: 'USD',
+    })
+    expect(result.success).toBe(false)
+    if (result.success) return
+    expect(result.error.issues.some((i) => i.path[0] === 'quantityAttributeCode')).toBe(true)
+  })
+
+  it('accepts flat + table without a quantity attribute', () => {
+    const result = cpqProductChargeCreateSchema.safeParse({
+      code: 'plat', name: 'Platform', chargeType: 'mrc',
+      chargeModel: 'flat', pricingMethod: 'table',
+      pricingTableId: VALID_UUID, priceColumnKey: 'list',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects flat + table with a stray quantity attribute', () => {
+    const result = cpqProductChargeCreateSchema.safeParse({
+      code: 'plat', name: 'Platform', chargeType: 'mrc',
+      chargeModel: 'flat', pricingMethod: 'table',
+      pricingTableId: VALID_UUID, priceColumnKey: 'list', quantityAttributeCode: 'seats',
+    })
+    expect(result.success).toBe(false)
+    if (result.success) return
+    expect(result.error.issues.some((i) => i.path[0] === 'quantityAttributeCode')).toBe(true)
+  })
 })
 
 describe('cpqPriceRuleCreateSchema', () => {

package/src/modules/cpq/data/charge-pricing.ts

@@ -0,0 +1,48 @@
+// XD-297: a charge's "shape" is two orthogonal axes:
+//   ChargeModel   — how quantity drives the charge.
+//   PricingSource — where the unit price comes from.
+// Pure, dependency-free helpers live in the data layer so validators, routes,
+// the pricing service, seeds, and the UI can all share them without reaching
+// across layers.
+export type ChargeModel = 'flat' | 'per_unit' | 'volume' | 'tiered'
+export type PricingSource = 'fixed' | 'table'
+
+/**
+ * Resolve a charge's (chargeModel, pricingSource) from either the new split
+ * columns or a legacy combined `pricingMethod` value (flat | per_unit | tiered).
+ * Keeps the engine working for rows that predate the split / haven't been
+ * migrated, and tolerates new clients that send the legacy value by mistake.
+ */
+export function normalizeChargePricing(charge: {
+  chargeModel?: string | null
+  pricingMethod?: string | null
+  fixedPrice?: string | null
+  pricingTableId?: string | null
+}): { model: ChargeModel; source: PricingSource } {
+  const pm = (charge.pricingMethod ?? '').toLowerCase()
+  // Anything that historically meant "comes from a table" maps to source=table.
+  const tableLike = pm === 'table' || pm === 'per_unit' || pm === 'tiered' || pm === 'volume'
+  const source: PricingSource = tableLike
+    ? 'table'
+    : pm === 'fixed'
+      ? 'fixed'
+      // Legacy 'flat' could be a fixed price OR a flat table lookup (the old
+      // `calculateFlat`-via-table path), empty, or unknown: infer from the
+      // presence of a pricing table — preserving that legacy behaviour.
+      : charge.pricingTableId
+        ? 'table'
+        : 'fixed'
+
+  const rawModel = (charge.chargeModel ?? '').toLowerCase()
+  const model: ChargeModel =
+    rawModel === 'flat' || rawModel === 'per_unit' || rawModel === 'volume' || rawModel === 'tiered'
+      ? (rawModel as ChargeModel)
+      // No explicit model → derive from the legacy combined pricingMethod.
+      : pm === 'per_unit'
+        ? 'per_unit'
+        : pm === 'tiered'
+          ? 'tiered'
+          : 'flat'
+
+  return { model, source }
+}

package/src/modules/cpq/data/entities.ts

@@ -515,6 +515,16 @@ export class CpqProductCharge {
   @Property({ name: 'charge_type', type: 'text' })
   chargeType!: string
 
+  // XD-297: charge "shape" split into two orthogonal axes.
+  //   chargeModel  — how quantity drives the charge: flat | per_unit | volume | tiered
+  //   pricingMethod — where the unit price comes from: fixed | table
+  // Legacy rows (pre-split) carry the old combined pricingMethod values
+  // (flat | per_unit | tiered); the migration backfills both columns and the
+  // pricing service normalises any that slip through. chargeModel is nullable
+  // so the additive migration is default-safe.
+  @Property({ name: 'charge_model', type: 'text', nullable: true })
+  chargeModel?: string | null
+
   @Property({ name: 'pricing_method', type: 'text' })
   pricingMethod!: string
 

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

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { normalizeChargePricing } from './charge-pricing'
 
 // ─── Product Specification ───────────────────────────────────────
 
@@ -140,9 +141,14 @@ export const cpqProductAttributeUpdateSchema = cpqProductAttributeCreateSchema.p
 // `fixed` is a legacy alias for `flat` — older seeds (`demo_puffin`,
 // `demo_gix`) emit it directly and ~30+ rows in prod use it. The pricing
 // service treats them identically (fixedPrice + currencyCode, no table
-// lookup). We accept it on input and normalise to `flat` so storage
-// stays canonical.
-const cpqChargePricingMethodEnum = z.enum(['flat', 'fixed', 'tiered', 'per_unit'])
+// lookup). XD-297 splits the charge "shape" into two axes — chargeModel
+// (flat | per_unit | volume | tiered) and pricingMethod (fixed | table).
+// Input accepts either the new split OR a legacy combined pricingMethod
+// (flat | per_unit | tiered); normalizeChargePricing() collapses both to a
+// canonical {model, source} that the route persists.
+const cpqChargeModelEnum = z.enum(['flat', 'per_unit', 'volume', 'tiered'])
+// New sources (fixed | table) plus the legacy combined values for back-compat.
+const cpqChargePricingMethodEnum = z.enum(['fixed', 'table', 'flat', 'tiered', 'per_unit'])
 
 const requireField = (
   ctx: z.RefinementCtx,
@@ -176,7 +182,8 @@ const cpqProductChargeBase = z.object({
   name: z.string().min(1),
   description: z.string().nullish(),
   chargeType: z.enum(['nrc', 'mrc', 'usage']),
-  pricingMethod: cpqChargePricingMethodEnum.transform((v) => (v === 'fixed' ? 'flat' : v)),
+  chargeModel: cpqChargeModelEnum.optional(),
+  pricingMethod: cpqChargePricingMethodEnum,
   pricingTableId: z.string().uuid().nullish(),
   priceColumnKey: z.string().nullish(),
   fixedPrice: z.union([z.string(), z.number().transform(String)]).nullish(),
@@ -187,15 +194,17 @@ const cpqProductChargeBase = z.object({
   isActive: z.boolean().optional().default(true),
 })
 
-// V-CHG-1: pricing method must match the configured fields.
-//  - flat     → fixedPrice + currencyCode required; table fields forbidden
-//  - per_unit → pricingTableId + priceColumnKey + quantityAttributeCode
-//               required; fixedPrice forbidden
-//  - tiered   → same as per_unit (rangeFrom/rangeTo come from the table)
+// V-CHG-1: the (chargeModel × pricingMethod) combination must match the fields.
+//  fixed  → fixedPrice + currencyCode required; table fields forbidden.
+//           flat: no quantity attr; per_unit: quantity attr required.
+//           volume / tiered + fixed is not a valid combination.
+//  table  → pricingTableId + priceColumnKey required; fixedPrice forbidden.
+//           flat: no quantity attr; per_unit / volume / tiered: quantity attr required.
 const refineChargePricingShape = (
   ctx: z.RefinementCtx,
   charge: {
-    pricingMethod?: 'flat' | 'tiered' | 'per_unit'
+    chargeModel?: 'flat' | 'per_unit' | 'volume' | 'tiered'
+    pricingMethod?: 'fixed' | 'table' | 'flat' | 'tiered' | 'per_unit'
     pricingTableId?: string | null
     priceColumnKey?: string | null
     fixedPrice?: string | null
@@ -203,21 +212,39 @@ const refineChargePricingShape = (
     quantityAttributeCode?: string | null
   },
 ) => {
-  const method = charge.pricingMethod
-  if (!method) return
-  if (method === 'flat') {
-    requireField(ctx, charge.fixedPrice, 'fixedPrice', 'V-CHG-1: fixedPrice is required for flat pricing')
-    requireField(ctx, charge.currencyCode, 'currencyCode', 'V-CHG-1: currencyCode is required for flat pricing')
-    forbidField(ctx, charge.pricingTableId, 'pricingTableId', 'V-CHG-1: pricingTableId must be empty for flat pricing')
-    forbidField(ctx, charge.priceColumnKey, 'priceColumnKey', 'V-CHG-1: priceColumnKey must be empty for flat pricing')
-    forbidField(ctx, charge.quantityAttributeCode, 'quantityAttributeCode', 'V-CHG-1: quantityAttributeCode must be empty for flat pricing')
+  if (charge.pricingMethod === undefined && charge.chargeModel === undefined) return
+  const { model, source } = normalizeChargePricing(charge)
+
+  if (source === 'fixed') {
+    if (model === 'volume' || model === 'tiered') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['pricingMethod'],
+        message: `V-CHG-1: ${model} pricing requires Table Lookup, not a fixed price`,
+      })
+      return
+    }
+    requireField(ctx, charge.fixedPrice, 'fixedPrice', 'V-CHG-1: fixedPrice is required for a fixed price')
+    requireField(ctx, charge.currencyCode, 'currencyCode', 'V-CHG-1: currencyCode is required for a fixed price')
+    forbidField(ctx, charge.pricingTableId, 'pricingTableId', 'V-CHG-1: pricingTableId must be empty for a fixed price')
+    forbidField(ctx, charge.priceColumnKey, 'priceColumnKey', 'V-CHG-1: priceColumnKey must be empty for a fixed price')
+    if (model === 'per_unit') {
+      requireField(ctx, charge.quantityAttributeCode, 'quantityAttributeCode', 'V-CHG-1: quantityAttributeCode is required for per-unit pricing')
+    } else {
+      forbidField(ctx, charge.quantityAttributeCode, 'quantityAttributeCode', 'V-CHG-1: quantityAttributeCode must be empty for a flat fixed price')
+    }
     return
   }
-  // per_unit | tiered
-  requireField(ctx, charge.pricingTableId, 'pricingTableId', `V-CHG-1: pricingTableId is required for ${method} pricing`)
-  requireField(ctx, charge.priceColumnKey, 'priceColumnKey', `V-CHG-1: priceColumnKey is required for ${method} pricing`)
-  requireField(ctx, charge.quantityAttributeCode, 'quantityAttributeCode', `V-CHG-1: quantityAttributeCode is required for ${method} pricing`)
-  forbidField(ctx, charge.fixedPrice, 'fixedPrice', `V-CHG-1: fixedPrice must be empty for ${method} pricing — price comes from the pricing table`)
+
+  // source === 'table'
+  requireField(ctx, charge.pricingTableId, 'pricingTableId', 'V-CHG-1: pricingTableId is required for table lookup')
+  requireField(ctx, charge.priceColumnKey, 'priceColumnKey', 'V-CHG-1: priceColumnKey is required for table lookup')
+  forbidField(ctx, charge.fixedPrice, 'fixedPrice', 'V-CHG-1: fixedPrice must be empty for table lookup — price comes from the table')
+  if (model === 'flat') {
+    forbidField(ctx, charge.quantityAttributeCode, 'quantityAttributeCode', 'V-CHG-1: quantityAttributeCode must be empty for a flat table price')
+  } else {
+    requireField(ctx, charge.quantityAttributeCode, 'quantityAttributeCode', `V-CHG-1: quantityAttributeCode is required for ${model} pricing`)
+  }
 }
 
 export const cpqProductChargeCreateSchema = cpqProductChargeBase.superRefine((data, ctx) => {
@@ -227,9 +254,12 @@ export const cpqProductChargeCreateSchema = cpqProductChargeBase.superRefine((da
 export const cpqProductChargeUpdateSchema = cpqProductChargeBase.partial().extend({
   id: z.string().uuid(),
 }).superRefine((data, ctx) => {
-  // On update, only enforce shape if pricingMethod is present in payload
-  // (PATCH semantics — service merges with the persisted row).
-  if (data.pricingMethod !== undefined) refineChargePricingShape(ctx, data)
+  // Enforce shape whenever either pricing axis is being changed — a
+  // chargeModel-only PATCH (e.g. flat → per_unit) still alters the required
+  // fields, so it must validate rather than silently persist a broken charge.
+  if (data.pricingMethod !== undefined || data.chargeModel !== undefined) {
+    refineChargePricingShape(ctx, data)
+  }
 })
 
 // ─── Price Rule ──────────────────────────────────────────────────

package/src/modules/cpq/events.ts

@@ -3,14 +3,22 @@ import { createModuleEvents } from '@open-mercato/shared/modules/events'
 /**
  * CPQ Module Events.
  *
- * Currently only the XD-250 ARC (Amend / Renew / Cancel) lifecycle events
- * are declared here. Downstream modules (billing, notifications) subscribe
- * to these to react to subscription mutations driven by CPQ orders.
+ * Subscription lifecycle events: `activated` (new-sale onboarding) plus
+ * the XD-250 ARC (Amend / Renew / Cancel / merge) events. Downstream
+ * modules (billing, notifications) subscribe to these to react to
+ * subscription mutations driven by CPQ orders.
  *
  * Emission rule: events fire AFTER the activation transaction commits.
  * `cpqOrderService.activateOrder` is the sole emitter site.
  */
 const events = [
+  {
+    id: 'cpq.subscription.activated',
+    label: 'Subscription Activated',
+    entity: 'subscription',
+    category: 'lifecycle',
+    clientBroadcast: true,
+  },
   {
     id: 'cpq.subscription.amended',
     label: 'Subscription Amended',

package/src/modules/cpq/lib/seeds/__tests__/demo.test.ts

@@ -0,0 +1,78 @@
+import { seedCpqDemo, resetCpqDemo } from '../demo'
+
+/**
+ * In-memory mock EM mirroring the seed's find-or-create contract:
+ * `findOne` matches the catalog product by `sku` and every CPQ row by
+ * `code`; `create` mints an id; `persist` stores; `nativeDelete` is counted.
+ */
+function makeMockEm() {
+  const store: Array<Record<string, unknown>> = []
+  let idSeq = 0
+  const em = {
+    store,
+    findOne: jest.fn(async (_entity: unknown, where: Record<string, unknown>) => {
+      return (
+        store.find((row) => {
+          if (typeof where.sku === 'string') return row.sku === where.sku
+          if (typeof where.code === 'string') return row.code === where.code
+          return false
+        }) ?? null
+      )
+    }),
+    create: jest.fn((_entity: unknown, data: Record<string, unknown>) => ({
+      id: `id-${++idSeq}`,
+      ...data,
+    })),
+    persist: jest.fn((entity: Record<string, unknown>) => {
+      store.push(entity)
+      return entity
+    }),
+    flush: jest.fn(async () => undefined),
+    nativeDelete: jest.fn(async () => 0),
+  }
+  return em as never as Parameters<typeof seedCpqDemo>[0] & {
+    store: Array<Record<string, unknown>>
+    nativeDelete: jest.Mock
+  }
+}
+
+const SCOPE = { tenantId: 'tnt-1', organizationId: 'org-1' }
+
+describe('seedCpqDemo', () => {
+  it('creates the product, spec, offering and charge on a fresh tenant', async () => {
+    const em = makeMockEm()
+    const res = await seedCpqDemo(em, SCOPE)
+    expect(res).toEqual({
+      productsCreated: 1,
+      specsCreated: 1,
+      offeringsCreated: 1,
+      chargesCreated: 1,
+    })
+  })
+
+  it('is idempotent — a second run creates nothing', async () => {
+    const em = makeMockEm()
+    await seedCpqDemo(em, SCOPE)
+    const second = await seedCpqDemo(em, SCOPE)
+    expect(second).toEqual({
+      productsCreated: 0,
+      specsCreated: 0,
+      offeringsCreated: 0,
+      chargesCreated: 0,
+    })
+  })
+
+  it('links the charge to the seeded offering (per-offering uniqueness)', async () => {
+    const em = makeMockEm()
+    await seedCpqDemo(em, SCOPE)
+    const offering = em.store.find((r) => r.code === 'DEMO-CPQ-CLOUD-OFFER') as { id: string }
+    const charge = em.store.find((r) => r.code === 'DEMO-CPQ-CLOUD-MRC') as { offeringId: string }
+    expect(charge?.offeringId).toBe(offering?.id)
+  })
+
+  it('reset issues a delete for charge, offering, spec and product', async () => {
+    const em = makeMockEm()
+    await resetCpqDemo(em, SCOPE)
+    expect(em.nativeDelete).toHaveBeenCalledTimes(4)
+  })
+})

package/src/modules/cpq/lib/seeds/demo.ts

@@ -0,0 +1,145 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+/**
+ * Minimal, self-contained CPQ test-data seed.
+ *
+ * Creates one neutral catalog product with a Specification, an Offering, and
+ * a fixed monthly charge — enough to exercise the CPQ admin (Product
+ * Specifications / Offerings lists) and quoting locally. Idempotent: every
+ * row is matched by a stable `DEMO-CPQ-*` code / sku, so re-running is a
+ * no-op rather than a duplicate.
+ *
+ * Intentionally generic (NOT customer-specific) so it ships with
+ * `@dainamite/cpq`. Rich, vertical demo catalogs live in the `demo_<x>`
+ * app modules + `mercato demo_tenants seed`.
+ */
+
+export type CpqDemoScope = { tenantId: string; organizationId: string }
+export type CpqDemoResult = {
+  productsCreated: number
+  specsCreated: number
+  offeringsCreated: number
+  chargesCreated: number
+}
+
+const PRODUCT_SKU = 'DEMO-CPQ-CLOUD'
+const SPEC_CODE = 'DEMO-CPQ-CLOUD-SPEC'
+const OFFERING_CODE = 'DEMO-CPQ-CLOUD-OFFER'
+const CHARGE_CODE = 'DEMO-CPQ-CLOUD-MRC'
+
+export async function resetCpqDemo(em: EntityManager, scope: CpqDemoScope): Promise<void> {
+  const { CpqProductSpecification, CpqProductOffering, CpqProductCharge } = await import(
+    '../../data/entities'
+  )
+  const { CatalogProduct } = await import('@open-mercato/core/modules/catalog/data/entities')
+  // Leaves first, roots last.
+  await em.nativeDelete(CpqProductCharge, { ...scope, code: CHARGE_CODE } as never)
+  await em.nativeDelete(CpqProductOffering, { ...scope, code: OFFERING_CODE } as never)
+  await em.nativeDelete(CpqProductSpecification, { ...scope, code: SPEC_CODE } as never)
+  await em.nativeDelete(CatalogProduct, { ...scope, sku: PRODUCT_SKU } as never)
+}
+
+export async function seedCpqDemo(
+  em: EntityManager,
+  scope: CpqDemoScope,
+  options: { reset?: boolean } = {},
+): Promise<CpqDemoResult> {
+  if (options.reset) await resetCpqDemo(em, scope)
+
+  const { CpqProductSpecification, CpqProductOffering, CpqProductCharge } = await import(
+    '../../data/entities'
+  )
+  const { CatalogProduct } = await import('@open-mercato/core/modules/catalog/data/entities')
+
+  const result: CpqDemoResult = {
+    productsCreated: 0,
+    specsCreated: 0,
+    offeringsCreated: 0,
+    chargesCreated: 0,
+  }
+
+  // ── Catalog product (idempotent by sku) ──
+  let product = await em.findOne(CatalogProduct, { ...scope, sku: PRODUCT_SKU, deletedAt: null } as never)
+  if (!product) {
+    product = em.create(CatalogProduct, {
+      ...scope,
+      title: 'Demo Cloud Plan',
+      sku: PRODUCT_SKU,
+      handle: PRODUCT_SKU.toLowerCase(),
+      productType: 'configurable',
+      description: 'Generic CPQ demo product seeded by `mercato cpq seed`.',
+      isConfigurable: true,
+      isActive: true,
+    })
+    em.persist(product)
+    await em.flush()
+    result.productsCreated += 1
+  }
+
+  // ── Specification (idempotent by code) ──
+  let spec = await em.findOne(CpqProductSpecification, { ...scope, code: SPEC_CODE, deletedAt: null } as never)
+  if (!spec) {
+    spec = em.create(CpqProductSpecification, {
+      ...scope,
+      productId: product.id,
+      code: SPEC_CODE,
+      name: 'Demo Cloud Specification',
+      specType: 'simple',
+      lifecycleStatus: 'active',
+      isActive: true,
+    })
+    em.persist(spec)
+    await em.flush()
+    result.specsCreated += 1
+  }
+
+  // ── Offering (idempotent by code) ──
+  let offering = await em.findOne(CpqProductOffering, { ...scope, code: OFFERING_CODE, deletedAt: null } as never)
+  if (!offering) {
+    offering = em.create(CpqProductOffering, {
+      ...scope,
+      specId: spec.id,
+      code: OFFERING_CODE,
+      name: 'Demo Cloud Offering',
+      offeringType: 'simple',
+      designTimeValues: {},
+      lifecycleStatus: 'active',
+      isActive: true,
+    })
+    em.persist(offering)
+    await em.flush()
+    result.offeringsCreated += 1
+  }
+
+  // ── Charge (idempotent by offering + code, matching the DB unique
+  //    constraint `(org, tenant, offering_id, code)`) — fixed monthly fee ──
+  const charge = await em.findOne(CpqProductCharge, {
+    ...scope,
+    offeringId: offering.id,
+    code: CHARGE_CODE,
+    deletedAt: null,
+  } as never)
+  if (!charge) {
+    em.persist(
+      em.create(CpqProductCharge, {
+        ...scope,
+        productId: product.id,
+        offeringId: offering.id,
+        code: CHARGE_CODE,
+        name: 'Monthly platform fee',
+        chargeType: 'mrc',
+        chargeModel: 'flat',
+        pricingMethod: 'fixed',
+        fixedPrice: '99.0000',
+        // Neutral default — this seed ships generically with @dainamite/cpq.
+        currencyCode: 'USD',
+        sortOrder: 0,
+        isActive: true,
+      }),
+    )
+    result.chargesCreated += 1
+  }
+
+  await em.flush()
+  return result
+}

package/src/modules/cpq/migrations/.snapshot-open-mercato.json

@@ -4320,6 +4320,22 @@
           "enumItems": [],
           "mappedType": "text"
         },
+        "charge_model": {
+          "name": "charge_model",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "enumItems": [],
+          "mappedType": "text"
+        },
         "pricing_method": {
           "name": "pricing_method",
           "type": "text",

package/src/modules/cpq/migrations/Migration20260602000000_cpq_charge_model_split.ts

@@ -0,0 +1,57 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * XD-297 — split the charge "shape" into two orthogonal axes.
+ *
+ * Before: `cpq_product_charges.pricing_method` conflated *how quantity drives
+ * the charge* (flat | per_unit | tiered) with *where the price comes from*
+ * (a fixed price for `flat`, a table lookup for `per_unit` / `tiered`).
+ *
+ * After:
+ *   - `charge_model`   — flat | per_unit | volume | tiered  (new column)
+ *   - `pricing_method` — fixed | table                       (repurposed)
+ *
+ * The backfill maps every legacy row to the equivalent split shape:
+ *   flat     → (charge_model=flat,     pricing_method=fixed)
+ *   per_unit → (charge_model=per_unit, pricing_method=table)
+ *   tiered   → (charge_model=tiered,   pricing_method=table)
+ *
+ * Hand-written because the data backfill (re-coding existing `pricing_method`
+ * values) is beyond what MikroORM's schema generator can emit. The pricing
+ * service additionally normalises any row that predates this migration, so the
+ * change is safe even before it is applied.
+ */
+export class Migration20260602000000_cpq_charge_model_split extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`alter table "cpq_product_charges" add column "charge_model" text null;`)
+
+    // Derive charge_model from the legacy combined pricing_method FIRST …
+    this.addSql(`update "cpq_product_charges" set "charge_model" = case
+      when "pricing_method" = 'per_unit' then 'per_unit'
+      when "pricing_method" = 'tiered' then 'tiered'
+      else 'flat'
+    end where "charge_model" is null;`)
+
+    // … then collapse pricing_method to the new {fixed, table} axis.
+    this.addSql(`update "cpq_product_charges" set "pricing_method" = case
+      when "pricing_method" in ('per_unit', 'tiered', 'volume', 'table') then 'table'
+      else 'fixed'
+    end;`)
+  }
+
+  async down(): Promise<void> {
+    // Best-effort re-collapse to the legacy combined value. `per_unit + fixed`
+    // reverts to `flat` (the old fixed-price path: 1 × fixedPrice) rather than
+    // `per_unit` (old table lookup) so it doesn't silently under-bill; only a
+    // genuine `per_unit + table` keeps the per_unit model. `volume` has no
+    // legacy equivalent and falls back to per_unit.
+    this.addSql(`update "cpq_product_charges" set "pricing_method" = case
+      when "charge_model" = 'tiered' then 'tiered'
+      when "charge_model" = 'per_unit' and "pricing_method" = 'table' then 'per_unit'
+      when "charge_model" = 'volume' then 'per_unit'
+      else 'flat'
+    end;`)
+
+    this.addSql(`alter table "cpq_product_charges" drop column "charge_model";`)
+  }
+}