Plaid v2: per-QLI SBQQ override fields, end-to-end

Threads three SBQQ override fields from Salesforce QLI read → reconstruction → schema → Plaid CPQ writeback so v2's payload stops dropping per-line values that v1 emits.

1. Why this exists

v1's CPQ writeback emits per-QLI values for three SBQQ override fields. v2's Plaid writeback never read them, never carried them through, and never wrote them — so the v1→v2 diff harness flagged the missing fields as structural diffs on every quote that used them.

2. The four-stage pipeline

The change is best understood as one value travelling through four stages. The carousel walks one override (SBQQ__ProrateMultiplier__c = 2) from Salesforce to the Plaid writeback payload.

3. The shape of sfdcQliOverrides

Rather than scattering raw SBQQ__* keys across the generic ProductInput surface, the PR adds a single nested, optional, nullable object. The keys are the raw SF field names — that's deliberate, so the writeback can splat them straight onto the QLI body without a rename layer.

// packages/types/v2/pricingQuoteInput.ts
sfdcQliOverrides: z
  .object({
    SBQQ__DefaultSubscriptionTerm__c: z.number().optional().nullable(),
    SBQQ__ProrateMultiplier__c:       z.number().optional().nullable(),
    AdditionalDiscountUnit__c:        z.string().optional().nullable(),
  })
  .optional()
  .nullable();

4. The collapse rule: first non-null wins

A product group may map to many QLIs (flat row, tier rows, segment rows). The three override fields live on every QLI, but ProductInput has one slot per field. pickSfdcQliOverrides walks the group's QLIs in input order and picks the first non-null value per field, independently.

// reconstructProductInputs.ts — the core loop
for (const qli of qlis) {
  if (defaultSubscriptionTerm == null && qli.SBQQ__DefaultSubscriptionTerm__c != null) {
    defaultSubscriptionTerm = qli.SBQQ__DefaultSubscriptionTerm__c;
  }
  if (prorateMultiplier == null && qli.SBQQ__ProrateMultiplier__c != null) {
    prorateMultiplier = qli.SBQQ__ProrateMultiplier__c;
  }
  if (additionalDiscountUnit == null && qli.AdditionalDiscountUnit__c != null) {
    additionalDiscountUnit = qli.AdditionalDiscountUnit__c;
  }
}

5. Emit precedence: input wins over canary default

The Plaid writeback already had a generic per-Product extraFields blob that gets spread onto every QLI body. The new override values must win over that default when both are present, matching v1's Order_Form_Product_Name__c precedence pattern.

// PlaidWriteBack.ts — buildPlaidQliTailFields
const qliOverrideTerm =
  sfdcQliOverrides?.SBQQ__DefaultSubscriptionTerm__c ??
  (extraFields?.SBQQ__DefaultSubscriptionTerm__c as number | undefined);
// ... ProrateMultiplier and AdditionalDiscountUnit follow the same pattern

return {
  ...(extraFields ?? {}),
  // ... existing tail fields ...
  ...(qliOverrideTerm !== undefined
    ? { SBQQ__DefaultSubscriptionTerm__c: qliOverrideTerm } : {}),
  ...(qliOverrideProrate !== undefined
    ? { SBQQ__ProrateMultiplier__c: qliOverrideProrate } : {}),
  ...(qliOverrideAdditionalDiscountUnit !== undefined
    ? { AdditionalDiscountUnit__c: qliOverrideAdditionalDiscountUnit } : {}),
};

6. Call-site coverage: all three QLI shapes

The Plaid writeback builds QLIs in three places, one per shape. sfdcQliOverrides is threaded into buildPlaidQliTailFields at each call site so the behaviour is uniform.

7. What it doesn't change

8. Tests

12 new unit tests across the three layers, written TDD / RED-first. Server tsc --noEmit clean, prettier clean.

9. Open question: harness re-run