fix(billing): v8.1 post-merge hardening

F1: wrap syncOrganizationPlan in try/catch in handleInvoicePaymentSucceeded —
    DB blip no longer dead-letters handler; emits billing.organization.sync_failed
F2: prepend '~' to synthetic event IDs in bumpEventMarkers — same-second lex
    tiebreaker now sorts synthetic bumps after Stripe evt_* IDs
F3: validatePlan warns on unrecognized non-empty planId before returning null
F4: add 'unpaid' to RECONCILE_STATUSES so reconciler covers unpaid subs
F5: add V8-C2b — canceled subscription in meter mode must be fail-closed

Author: PierreBrisorgueil

modules/billing/lib/billing.markerBump.js

@@ -13,6 +13,6 @@ export const bumpEventMarkers = (family, source) => {
   const fieldPrefix = family === 'invoice' ? 'lastInvoiceEvent' : 'lastSubscriptionEvent';
   return {
     [`${fieldPrefix}CreatedAt`]: Math.floor(ms / 1000),
-    [`${fieldPrefix}Id`]: `${source}-${ms}`,
+    [`${fieldPrefix}Id`]: `~${source}-${ms}`,
   };
 };

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', 'trialing'];
+const RECONCILE_STATUSES = ['active', 'past_due', 'trialing', 'unpaid'];
 
 /**
  * Valid plan names from config.

modules/billing/services/billing.webhook.service.js

@@ -42,7 +42,11 @@ const validPlans = new Set(config.billing?.plans || ['free', 'starter', 'pro', '
  * @param {string} plan - The plan name to validate.
  * @returns {string|null} The plan name if valid, null otherwise.
  */
-const validatePlan = (plan) => (validPlans.has(plan) ? plan : null);
+const validatePlan = (plan) => {
+  if (validPlans.has(plan)) return plan;
+  if (plan) logger.warn('[billing.webhook] validatePlan: unrecognized planId', { raw: plan, validPlans: [...validPlans] });
+  return null;
+};
 
 /**
  * Plan rank lookup — higher index means higher-tier plan.
@@ -601,7 +605,21 @@ const handleInvoicePaymentSucceeded = async (invoice, event) => {
   }
 
   if (isPastDue && resolvedPlan) {
-    await syncOrganizationPlan(organizationId, resolvedPlan);
+    try {
+      await syncOrganizationPlan(organizationId, resolvedPlan);
+    } catch (syncErr) {
+      logger.error('[billing.webhook] syncOrganizationPlan failed (non-fatal)', {
+        organizationId,
+        error: syncErr?.message ?? String(syncErr),
+      });
+      try {
+        billingEvents.emit('billing.organization.sync_failed', { organizationId, source: 'dunning_recovery' });
+      } catch (evtErr) {
+        logger.error('[billing.webhook] billing.organization.sync_failed listener error (non-fatal)', {
+          error: evtErr?.message ?? String(evtErr),
+        });
+      }
+    }
   }
 };
 

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

@@ -449,7 +449,7 @@ describe('BillingAdminService unit tests:', () => {
 
       expect(lastSubscriptionEventCreatedAt).toBeGreaterThanOrEqual(before);
       expect(lastSubscriptionEventCreatedAt).toBeLessThanOrEqual(after);
-      expect(lastSubscriptionEventId).toMatch(/^admin-cancel-\d+$/);
+      expect(lastSubscriptionEventId).toMatch(/^~admin-cancel-\d+$/);
     });
   });
 

modules/billing/tests/billing.quota.unit.tests.js

@@ -621,5 +621,29 @@ describe('requireQuota middleware:', () => {
       // Fail-closed branch must short-circuit before the meter check
       expect(mockBillingUsageService.getMeter).not.toHaveBeenCalled();
     });
+
+    test('V8-C2b: canceled subscription in meter mode → 402 METER_EXHAUSTED with free quota (not paid)', async () => {
+      // Org has status='canceled' (subscription ended). Paid plan must NOT bleed through.
+      // Fail-closed branch routes to free plan, same as incomplete.
+      mockSubscriptionRepository.findByOrganization.mockResolvedValue({ plan: 'pro', status: 'canceled' });
+      mockBillingUsageService.getMeter.mockResolvedValue(null);
+      mockBillingExtraBalanceRepository.getBalance.mockResolvedValue(0);
+      mockBillingPlanService.getActivePlan.mockReturnValue({ meterQuota: 0, version: 'v1' });
+
+      await requireQuota('scraps', 'create')(req, res, next);
+
+      expect(next).not.toHaveBeenCalled();
+      expect(res.status).toHaveBeenCalledWith(402);
+      const payload = res.json.mock.calls[0][0];
+      const errData = JSON.parse(payload.error);
+      expect(errData.type).toBe('METER_EXHAUSTED');
+      // Free plan quota (0), not the pro paid quota
+      expect(errData.meterQuota).toBe(0);
+      // getActivePlan called with the free/default plan id, not 'pro'
+      expect(mockBillingPlanService.getActivePlan).toHaveBeenCalledWith('free');
+      expect(mockBillingPlanService.getActivePlan).not.toHaveBeenCalledWith('pro');
+      // Fail-closed branch must short-circuit before the meter check
+      expect(mockBillingUsageService.getMeter).not.toHaveBeenCalled();
+    });
   });
 });

modules/billing/tests/billing.subscription.repository.unit.tests.js

@@ -409,7 +409,7 @@ describe('BillingSubscriptionRepository unit tests:', () => {
 
       expect(lastSubscriptionEventCreatedAt).toBeGreaterThanOrEqual(before);
       expect(lastSubscriptionEventCreatedAt).toBeLessThanOrEqual(after);
-      expect(lastSubscriptionEventId).toMatch(/^admin-bump-\d+$/);
+      expect(lastSubscriptionEventId).toMatch(/^~admin-bump-\d+$/);
     });
   });
 
@@ -433,7 +433,7 @@ describe('BillingSubscriptionRepository unit tests:', () => {
 
       expect(lastSubscriptionEventCreatedAt).toBeGreaterThanOrEqual(before);
       expect(lastSubscriptionEventCreatedAt).toBeLessThanOrEqual(after);
-      expect(lastSubscriptionEventId).toMatch(/^dunning-\d+$/);
+      expect(lastSubscriptionEventId).toMatch(/^~dunning-\d+$/);
     });
   });
 });