Renewal scaffold on Closed Won

Drive the in-system renewal contract + draft quote off the Salesforce Closed Won event, instead of waiting for the renewal opportunity to drift in through CRM sync.

1. Why this exists

For the Langchain engagement-contract model, when a deal hits Salesforce Closed Won two things have to happen in lockstep:

1. Write the deal group back to Salesforce — already wired via langchainDealGroupSync.
2. Keep an in-system renewal in sync — this PR.

2. The Closed Won flow, step by step

Step through what happens when a contract head goes Closed Won. State colors follow the legend above.

3. What changes, file by file

4. How the orchestrator branches

The branch is chosen by a single lookup — findPendingRenewalSuccessorOpp(priorDealGroupId). Returns an opp id → refresh. Returns null → create.

5. Idempotency & self-healing

The orchestrator runs from a BullMQ-retried listener, so every step has to tolerate replay. There are two failure points between "decision made" and "all rows written":

6. Two reactors, one orchestrator

The PR adds two listeners that both call ensureRenewalForClosedWonContract. They cover different signals.

7. The Deal_Group__c reconciliation event

A new event type rides on a new webhook branch in processAmpersandWebhook. The filter is the embedded Deal_Group_Id__c field we stamp on writeback — deal groups we didn't create won't carry an id we recognize, so they fall out at the prisma lookup.

// processAmpersandWebhook.ts — new branch
} else if (
  DEAL_GROUP_WEBHOOK_OBJECT &&
  objectName === DEAL_GROUP_WEBHOOK_OBJECT &&
  Array.isArray(payload.result)
) {
  for (const item of payload.result) {
    await processDealGroupResultItem({ item, svixId });
  }
}

// ...inside processDealGroupResultItem:
const ourDealGroupId = fields?.[DEAL_GROUP_ID_WEBHOOK_FIELD];
const dealGroup = await prisma.dealGroup.findUnique({
  where: { id: ourDealGroupId },
  select: { id: true, organizationId: true },
});
if (!dealGroup) return; // not one of ours

await tryEmit('crm.deal_group_updated', {
  organizationId: dealGroup.organizationId,
  entityId: dealGroup.id,
  payload: { dealGroupId: dealGroup.id, renewalOpportunitySfdcId, ... },
});

8. Enrichment dedupe

The other half of the dedupe story: when the renewal opp does eventually sync through CRM, the enrichment decider used to take the create-renewal path unconditionally. Now it checks first:

case 'create-renewal': {
  const existingRenewalOppId = await findPendingRenewalSuccessorOpp(
    intent.priorDealGroupId,
  );
  if (existingRenewalOppId) {
    logger.info(`[Langchain enrich] create-renewal SKIP — a PENDING renewal already exists ...`);
    return;
  }
  // ...fall through to original creation logic
}

So whichever signal arrives first — Closed Won on the prior, the Deal_Group__c link, or the renewal opp itself — exactly one PENDING renewal contract is created per prior.

9. What this PR doesn't change

10. Risks, gating & open extension points

Open extension points (called out in the PR)

• Eager create + enrich of the renewal opp (current code defers when the renewal opp isn't synced and no SOQL link exists, rather than fabricating CRM opp data).
• Renewal activation lifecycle — the natural follow-up PR.
• Opportunity-side renewal-link webhook field (RENEWAL_LINK_WEBHOOK_FIELD) — already wired through renewalLinkObserved if a preferred signal emerges.