feat(billing): lastResetAt + archivedAt schema + meter cap (PR-N8) (#3557)

* feat(billing): lastResetAt + archivedAt schema + meter cap (PR-N8)

P2.8 + P2.9 + P2.12 — robustness pass on the billing surface.

- P2.8: Subscription gains lastResetAt field. New repository method
        findAllDueForResetByLastReset(now) replaces the 7-day window query
        (resilient to scheduler delays beyond a week). resetAllDue persists
        lastResetAt after each successful resetWeek. Legacy findAllDueForReset
        kept and marked @deprecated for backward compat.
- P2.9: BillingUsage Mongoose + Zod schema declares archivedAt: Date|null.
        archiveOtherWeeks() now queries by archivedAt: null instead of
        $exists: false, matching the schema-default behavior. Without this
        the field was silently stripped on write per Mongoose strict mode.
- P2.12: meter.service.attribute() applies maxUnitsPerOperation as a
         clamp+warn before incrementMeter. Feature breakdown is rescaled
         proportionally so persisted bucket totals stay consistent with
         meterUsed.

Also updates scripts/tests/billing.cron.weeklyReset.unit.tests.js to mock
the new findAllDueForResetByLastReset + updateLastResetAt methods.

* fix(billing): capBreakdown — proportional rescaling + Object.create(null) + isCapped var

- Replace greedy strategy with proportional rescaling (ratio × floor + remainder
  distributed to largest buckets) so breakdown buckets always sum to cappedUnits
  exactly, matching the 'rescaled proportionally' intent in the PR description.
- Use Object.create(null) for cappedBreakdown to prevent prototype pollution
  (Codacy HIGH risk).
- Extract isCapped boolean to eliminate the redundant cappedUnits < totalUnits
  double-check (Codacy LOW risk).
- Pass originalTotal as a third arg to capBreakdown from attribute().
- Add 3 direct unit tests for capBreakdown (proportional multi-key, floor
  remainder distribution, empty breakdown) as flagged missing by Codacy.

Author: PierreBrisorgueil

modules/billing/models/billing.subscription.model.mongoose.js

@@ -71,6 +71,14 @@ const SubscriptionMongoose = new Schema(
       type: Date,
       default: null,
     },
+    /**
+     * Timestamp of the last successful weekly meter reset sweep.
+     * Used by the scheduler to recover after delayed or missed runs.
+     */
+    lastResetAt: {
+      type: Date,
+      default: null,
+    },
   },
   {
     timestamps: true,

modules/billing/models/billing.subscription.schema.js

@@ -24,6 +24,7 @@ const baseShape = {
   planVersion: z.string().trim().optional(),
   currentPeriodStart: z.coerce.date().nullable().optional(),
   pastDueSince: z.coerce.date().nullable().optional(),
+  lastResetAt: z.coerce.date().nullable().optional(),
 };
 
 const Subscription = z.object({

modules/billing/models/billing.usage.model.mongoose.js

@@ -97,6 +97,13 @@ const UsageMongoose = new Schema(
       type: Date,
       default: null,
     },
+    /**
+     * Timestamp when this usage period was archived by the reset sweep.
+     */
+    archivedAt: {
+      type: Date,
+      default: null,
+    },
     /**
      * ObjectIds of History documents consumed (attributed) this period.
      * Used for idempotent attribution checks.

modules/billing/models/billing.usage.schema.js

@@ -36,6 +36,7 @@ const BillingUsage = z.object({
   resetAt: z.coerce.date().optional().nullable(),
   alertedAt80: z.coerce.date().optional().nullable(),
   alertedAt100: z.coerce.date().optional().nullable(),
+  archivedAt: z.coerce.date().optional().nullable(),
 
   /**
    * Array of ObjectIds of History documents attributed to this period.

modules/billing/repositories/billing.subscription.repository.js

@@ -128,6 +128,7 @@ const findPlan = (organizationId) => {
  * @description Fetch active/trialing subscriptions whose currentPeriodStart falls
  *              within the provided time window. Used by the weekly meter reset sweep.
  *              Returns lean plain objects (no population) for performance.
+ * @deprecated Prefer findAllDueForResetByLastReset() for scheduler-delay resilience.
  * @param {Date} from - The start of the window (inclusive).
  * @param {Date} to - The end of the window (inclusive).
  * @returns {Promise<Array<{organization: string, currentPeriodStart: Date}>>}
@@ -142,6 +143,52 @@ const findAllDueForReset = (from, to) =>
     { organization: 1, currentPeriodStart: 1 },
   ).lean();
 
+/**
+ * @function findAllDueForResetByLastReset
+ * @description Fetch active/trialing subscriptions whose last successful reset is missing
+ *              or older than 7 days. Filters out subscriptions without currentPeriodStart
+ *              because resetWeek derives the next usage period from that timestamp.
+ *              Returns lean plain objects (no population) for performance.
+ * @param {Date} now - The current timestamp used to compute the stale-reset threshold.
+ * @returns {Promise<Array<{organization: string, currentPeriodStart: Date, lastResetAt: Date|null}>>}
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js repository, not Qwik
+const findAllDueForResetByLastReset = (now) => {
+  if (!(now instanceof Date)) throw new TypeError('now must be a Date instance');
+  const threshold = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+
+  return Subscription.find(
+    {
+      status: { $in: ['active', 'trialing'] },
+      currentPeriodStart: { $ne: null },
+      $or: [
+        { lastResetAt: null },
+        { lastResetAt: { $lt: threshold } },
+      ],
+    },
+    { organization: 1, currentPeriodStart: 1, lastResetAt: 1 },
+  ).lean();
+};
+
+/**
+ * @function updateLastResetAt
+ * @description Update the last successful reset timestamp for a subscription by organization.
+ * @param {string} organizationId - The organization ObjectId (string).
+ * @param {Date} date - The timestamp to persist.
+ * @returns {Promise<Object|null>} The updated subscription document, or null if the id is invalid.
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js repository, not Qwik
+const updateLastResetAt = (organizationId, date) => {
+  if (!mongoose.Types.ObjectId.isValid(organizationId)) return null;
+  if (!(date instanceof Date)) throw new TypeError('date must be a Date instance');
+
+  return Subscription.findOneAndUpdate(
+    { organization: organizationId },
+    { $set: { lastResetAt: date } },
+    { returnDocument: 'after', runValidators: true },
+  ).exec();
+};
+
 /**
  * @function findStaleDunning
  * @description Fetch subscriptions with status 'past_due' whose pastDueSince is set
@@ -191,6 +238,8 @@ export default {
   findByStripeCustomerId,
   findByStripeSubscriptionId,
   findAllDueForReset,
+  findAllDueForResetByLastReset,
+  updateLastResetAt,
   findStaleDunning,
   markUnpaid,
 };

modules/billing/repositories/billing.usage.repository.js

@@ -176,7 +176,7 @@ const archiveOtherWeeks = (orgId, currentWeekKey, archivedAt) =>
     {
       organizationId: orgId,
       weekKey: { $ne: currentWeekKey },
-      archivedAt: { $exists: false },
+      archivedAt: null,
     },
     { $set: { archivedAt } },
   );

modules/billing/services/billing.meter.service.js

@@ -56,6 +56,49 @@ const unitsFromCosts = async (costs, planId, ratioVersion) => {
   return { totalUnits, breakdown };
 };
 
+/**
+ * @function capBreakdown
+ * @description Rescale a feature breakdown map proportionally so its summed units do not exceed
+ *              the capped total. Each bucket is scaled by (cappedUnits / originalTotal) and
+ *              floored; any remainder is distributed to the largest remaining buckets so that
+ *              sum(result) === cappedUnits exactly.
+ * @param {Object} breakdown - Feature-keyed units map.
+ * @param {number} cappedUnits - Final capped total units to apply.
+ * @param {number} originalTotal - Original uncapped total (used as the scaling denominator).
+ * @returns {Object} Proportionally rescaled feature-keyed units map.
+ */
+const capBreakdown = (breakdown, cappedUnits, originalTotal) => {
+  if (!breakdown || typeof breakdown !== 'object' || cappedUnits === Infinity) return breakdown;
+
+  const entries = Object.entries(breakdown).filter(
+    ([, value]) => Number.isFinite(value) && value > 0,
+  );
+  if (entries.length === 0 || originalTotal <= 0) return Object.create(null);
+
+  const ratio = cappedUnits / originalTotal;
+  const cappedBreakdown = Object.create(null);
+  let allocated = 0;
+
+  for (const [key, value] of entries) {
+    const scaled = Math.floor(value * ratio);
+    cappedBreakdown[key] = scaled;
+    allocated += scaled;
+  }
+
+  // Distribute remainder (due to floor) to the largest buckets first
+  let remainder = cappedUnits - allocated;
+  if (remainder > 0) {
+    const sorted = entries.slice().sort(([, a], [, b]) => b - a);
+    for (const [key] of sorted) {
+      if (remainder <= 0) break;
+      cappedBreakdown[key] += 1;
+      remainder -= 1;
+    }
+  }
+
+  return cappedBreakdown;
+};
+
 /**
  * @function attribute
  * @description Attribute meter units from a History-like input to a Usage document
@@ -90,12 +133,22 @@ const attribute = async (history, organizationId) => {
     ({ totalUnits, breakdown } = await unitsFromCosts(history.costs, planId, ratioVersion));
   }
 
+  const maxUnits = config?.billing?.meter?.maxUnitsPerOperation ?? Infinity;
+  const cappedUnits = Math.min(totalUnits, maxUnits);
+  const isCapped = cappedUnits < totalUnits;
+  const cappedBreakdown = isCapped ? capBreakdown(breakdown, cappedUnits, totalUnits) : breakdown;
+  if (isCapped) {
+    console.warn(
+      `[billing.meter] units capped: requested ${totalUnits}, cap ${maxUnits}, applied ${cappedUnits}`,
+    );
+  }
+
   const idempotencyKey = history._id?.toString?.() ?? String(history._id);
 
   const result = await BillingUsageService.incrementMeter(
     organizationId,
-    totalUnits,
-    breakdown,
+    cappedUnits,
+    cappedBreakdown,
     idempotencyKey,
   );
 
@@ -122,5 +175,6 @@ const attribute = async (history, organizationId) => {
 export default {
   unitsFromCosts,
   attribute,
+  capBreakdown,
   METER_RUN_BASE,
 };

modules/billing/services/billing.reset.service.js

@@ -103,18 +103,15 @@ const resetAllDue = async () => {
   if (!config?.billing?.meterMode) return { processed: 0, errors: 0 };
 
   const now = new Date();
-  const oneWeekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
-
-  // Find subscriptions whose period started within the last week.
-  // TODO PR-N5: replace window query with lastResetAt field for scheduler-delay resilience.
-  const subs = await BillingSubscriptionRepository.findAllDueForReset(oneWeekAgo, now);
+  const subs = await BillingSubscriptionRepository.findAllDueForResetByLastReset(now);
 
   let processed = 0;
   let errors = 0;
 
   for (const sub of subs) {
     try {
       await resetWeek(String(sub.organization), new Date(sub.currentPeriodStart));
+      await BillingSubscriptionRepository.updateLastResetAt(String(sub.organization), now);
       processed += 1;
     } catch (err) {
       errors += 1;

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

@@ -10,6 +10,8 @@ describe('BillingMeterService unit tests:', () => {
   let BillingMeterService;
   let mockBillingPlanService;
   let mockConfig;
+  let mockBillingUsageService;
+  let mockBillingExtraService;
 
   const orgId = '507f1f77bcf86cd799439011';
 
@@ -48,6 +50,14 @@ describe('BillingMeterService unit tests:', () => {
       getActivePlan: jest.fn(),
     };
 
+    mockBillingUsageService = {
+      incrementMeter: jest.fn(),
+    };
+
+    mockBillingExtraService = {
+      debit: jest.fn(),
+    };
+
     jest.unstable_mockModule('../../../config/index.js', () => ({
       default: mockConfig,
     }));
@@ -56,6 +66,14 @@ describe('BillingMeterService unit tests:', () => {
       default: mockBillingPlanService,
     }));
 
+    jest.unstable_mockModule('../services/billing.usage.service.js', () => ({
+      default: mockBillingUsageService,
+    }));
+
+    jest.unstable_mockModule('../services/billing.extra.service.js', () => ({
+      default: mockBillingExtraService,
+    }));
+
     const mod = await import('../services/billing.meter.service.js');
     BillingMeterService = mod.default;
   });
@@ -155,4 +173,132 @@ describe('BillingMeterService unit tests:', () => {
       expect(result.meterUsed).toBe(0);
     });
   });
+
+  describe('attribute — maxUnitsPerOperation cap', () => {
+    test('caps metered units when computed units exceed config cap', async () => {
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+      mockBillingPlanService.getPlanByVersion.mockResolvedValue(makePlan({ ratios: { scrap: 1 } }));
+      mockBillingUsageService.incrementMeter.mockResolvedValue({
+        applied: true,
+        meterUsed: 10000,
+        extrasConsumed: 0,
+      });
+
+      const history = {
+        _id: '507f1f77bcf86cd799439033',
+        costs: { scrap: 20 },
+        planId: 'pro',
+        planVersion: 'v1',
+      };
+
+      const result = await BillingMeterService.attribute(history, orgId);
+
+      expect(mockBillingUsageService.incrementMeter).toHaveBeenCalledWith(
+        orgId,
+        10000,
+        { scrap: 10000 },
+        '507f1f77bcf86cd799439033',
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[billing.meter] units capped: requested 20000, cap 10000, applied 10000',
+      );
+      expect(result).toEqual({ applied: true, meterUsed: 10000, extrasConsumed: 0 });
+    });
+
+    test('does not clamp when units are within the configured cap', async () => {
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+      mockBillingPlanService.getPlanByVersion.mockResolvedValue(makePlan({ ratios: { scrap: 1 } }));
+      mockBillingUsageService.incrementMeter.mockResolvedValue({
+        applied: true,
+        meterUsed: 5000,
+        extrasConsumed: 0,
+      });
+
+      const history = {
+        _id: '507f1f77bcf86cd799439034',
+        costs: { scrap: 5 },
+        planId: 'pro',
+        planVersion: 'v1',
+      };
+
+      await BillingMeterService.attribute(history, orgId);
+
+      expect(mockBillingUsageService.incrementMeter).toHaveBeenCalledWith(
+        orgId,
+        5000,
+        { scrap: 5000 },
+        '507f1f77bcf86cd799439034',
+      );
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    test('does not clamp when maxUnitsPerOperation is undefined', async () => {
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+      delete mockConfig.billing.meter.maxUnitsPerOperation;
+      mockBillingPlanService.getPlanByVersion.mockResolvedValue(makePlan({ ratios: { scrap: 1 } }));
+      mockBillingUsageService.incrementMeter.mockResolvedValue({
+        applied: true,
+        meterUsed: 20000,
+        extrasConsumed: 0,
+      });
+
+      const history = {
+        _id: '507f1f77bcf86cd799439035',
+        costs: { scrap: 20 },
+        planId: 'pro',
+        planVersion: 'v1',
+      };
+
+      await BillingMeterService.attribute(history, orgId);
+
+      expect(mockBillingUsageService.incrementMeter).toHaveBeenCalledWith(
+        orgId,
+        20000,
+        { scrap: 20000 },
+        '507f1f77bcf86cd799439035',
+      );
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('capBreakdown — proportional rescaling', () => {
+    test('rescales a multi-key breakdown proportionally to the capped total', async () => {
+      const mod = await import('../services/billing.meter.service.js');
+      const { capBreakdown } = mod.default;
+
+      // breakdown: { scrap: 6000, autofix: 4000 } → total = 10000, cap to 5000
+      // scrap:  floor(6000 * 5000/10000) = 3000
+      // autofix: floor(4000 * 5000/10000) = 2000
+      // allocated = 5000, remainder = 0
+      const result = capBreakdown({ scrap: 6000, autofix: 4000 }, 5000, 10000);
+
+      expect(result.scrap).toBe(3000);
+      expect(result.autofix).toBe(2000);
+      expect(result.scrap + result.autofix).toBe(5000);
+    });
+
+    test('distributes floor remainder to the largest bucket first', async () => {
+      const mod = await import('../services/billing.meter.service.js');
+      const { capBreakdown } = mod.default;
+
+      // breakdown: { a: 3, b: 2, c: 1 } → total = 6, cap to 4
+      // a: floor(3 * 4/6) = floor(2) = 2
+      // b: floor(2 * 4/6) = floor(1.33) = 1
+      // c: floor(1 * 4/6) = floor(0.66) = 0
+      // allocated = 3, remainder = 1 → add 1 to largest bucket (a)
+      const result = capBreakdown({ a: 3, b: 2, c: 1 }, 4, 6);
+
+      expect(result.a + result.b + (result.c ?? 0)).toBe(4);
+      expect(result.a).toBeGreaterThanOrEqual(result.b);
+    });
+
+    test('returns empty object when breakdown has no valid entries', async () => {
+      const mod = await import('../services/billing.meter.service.js');
+      const { capBreakdown } = mod.default;
+
+      const result = capBreakdown({}, 5000, 10000);
+
+      expect(Object.keys(result)).toHaveLength(0);
+    });
+  });
 });