fix(billing): reconcile trialing subscriptions (#3626)

* fix(billing): include trialing subscriptions in reconciliation sweep

Add 'trialing' to RECONCILE_STATUSES so orgs on a trial period are
included in the weekly Stripe↔DB reconciliation. Previously they were
invisible until transitioning to active/past_due (7-14 day blind spot).

* docs(billing): update runReconciliation JSDoc to reflect trialing status

Author: PierreBrisorgueil

modules/billing/services/billing.reconcile.service.js

@@ -15,7 +15,7 @@ const RECONCILE_PAGE_SIZE = 100;
 /**
  * Statuses reconciled against Stripe.
  */
-const RECONCILE_STATUSES = ['active', 'past_due'];
+const RECONCILE_STATUSES = ['active', 'past_due', 'trialing'];
 
 /**
  * Valid plan names from config.
@@ -37,7 +37,7 @@ const resolveStripePlan = (subscription) => {
 
 /**
  * @function runReconciliation
- * @description Paginate all active|past_due subscriptions, fetch live Stripe status for each,
+ * @description Paginate all active|past_due|trialing subscriptions, fetch live Stripe status for each,
  *              and emit billing.reconciliation.divergence when status or plan diverges.
  *
  *              LOG-ONLY policy: this function NEVER writes to the DB or Stripe.

modules/billing/tests/billing.reconcile.service.unit.tests.js

@@ -182,6 +182,25 @@ describe('BillingReconcileService.runReconciliation unit tests:', () => {
     );
   });
 
+  test('detects plan drift on trialing sub — emits billing.reconciliation.divergence (C4)', async () => {
+    const sub = makeDbSub({ status: 'trialing', plan: 'pro' });
+    mockSubscriptionRepository.findPageForReconciliation
+      .mockResolvedValueOnce([sub])
+      .mockResolvedValue([]);
+    // Stripe has plan: starter — simulates Dashboard bump with lost webhook
+    mockStripeInstance.subscriptions.retrieve.mockResolvedValue(
+      makeStripeSub({ status: 'trialing', items: { data: [{ price: { metadata: { planId: 'starter' } } }] } }),
+    );
+
+    const result = await BillingReconcileService.runReconciliation();
+
+    expect(result).toMatchObject({ checked: 1, divergences: 1, errors: 0 });
+    expect(mockEvents.emit).toHaveBeenCalledWith(
+      'billing.reconciliation.divergence',
+      expect.objectContaining({ organizationId: orgId, planMismatch: true }),
+    );
+  });
+
   test('counts errors and continues on individual Stripe retrieve failure', async () => {
     const subs = [makeDbSub(), makeDbSub({ _id: 'sub_doc_002', stripeSubscriptionId: 'sub_test_002' })];
     mockSubscriptionRepository.findPageForReconciliation