fix(billing): address Copilot review — enum validation, accurate comments

- creditGrant now validates source via Zod (ExtraBalanceCreditGrant.parse) before write —
  findOneAndUpdate does not run validators so the explicit parse is necessary
- Add test for Zod throw on invalid source enum value
- Fix index comment: $ne predicate does not use tight index bounds (noted actual benefit)
- Fix GrantSource/LedgerEntry comments: creditCompensation does NOT set source; source
  is exclusively set by creditGrant and future grant methods

Author: PierreBrisorgueil

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

@@ -139,9 +139,12 @@ ExtraBalanceMongoose.index({ 'ledger.historyId': 1 }, { sparse: true });
 ExtraBalanceMongoose.index({ 'ledger.expiresAt': 1 }, { sparse: true });
 
 /**
- * Index for grant idempotency — supports creditGrant duplicate-check via refId filter.
- * refId is the leading key so the `ledger.refId: {$ne: key}` query uses index bounds directly.
- * source is a trailing key for analytics queries filtering grant entries by source.
+ * Index for grant analytics + idempotency support.
+ * refId is the leading key for analytics and admin queries that filter grant entries by refId prefix.
+ * source is a trailing key for filtering entries by grant type (e.g. all signup_grant entries).
+ * Note: the creditGrant idempotency guard (`ledger.refId: {$ne: key}`) is an exclusion predicate
+ * scoped by the unique `organization` field — it does not use tight index bounds, but the sparse
+ * index still reduces the scan set to grant entries only.
  */
 ExtraBalanceMongoose.index({ 'ledger.refId': 1, 'ledger.source': 1 }, { sparse: true });
 

modules/billing/models/billing.extraBalance.schema.js

@@ -16,12 +16,13 @@ const LedgerKind = z.enum(['topup', 'debit', 'refund', 'expiration', 'adjustment
 
 /**
  * Allowed grant sources — mirrors the Mongoose enum on LedgerEntrySchema.source.
- * 'signup_grant' — one-shot free tier grant on org creation.
- * 'adjustment'   — manual ops credit (non-Stripe, no Stripe session).
- * NOTE: 'adjustment' here is a source tag (who credited it), distinct from
- * LedgerKind 'adjustment' (how the balance was changed). They share the string
- * literal by convention: a manual adjustment uses kind='adjustment' + source='adjustment'.
- * Grant entries use kind='topup' + source='signup_grant'.
+ * 'signup_grant' — one-shot free tier grant on org creation (kind='topup').
+ * 'adjustment'   — reserved for future non-Stripe manual credits.
+ * NOTE: 'adjustment' here is a source tag (provenance), distinct from
+ * LedgerKind 'adjustment' (balance mutation type). Existing creditCompensation()
+ * writes kind='adjustment' entries WITHOUT setting source — source is only set by
+ * creditGrant() and future grant methods. Do not assume kind='adjustment' implies
+ * source='adjustment'.
  */
 const GrantSource = z.enum(['signup_grant', 'adjustment']);
 
@@ -51,7 +52,8 @@ const LedgerEntry = z
       .nullable(),
     refId: z.string().trim().optional().nullable(),
     /**
-     * Credit source tag — set on grant/adjustment entries; absent on Stripe topup entries.
+     * Credit source tag — set only by creditGrant() (and future grant methods).
+     * Absent on Stripe topup entries (creditPack) and creditCompensation entries.
      * Mirrors LedgerEntrySchema.source in billing.extraBalance.model.mongoose.js.
      */
     source: GrantSource.optional().nullable(),

modules/billing/repositories/billing.extraBalance.repository.js

@@ -3,6 +3,7 @@
  */
 import mongoose from 'mongoose';
 import AppError from '../../../lib/helpers/AppError.js';
+import BillingExtraBalanceSchema from '../models/billing.extraBalance.schema.js';
 
 /**
  * Validate that orgId is a syntactically valid MongoDB ObjectId.
@@ -183,12 +184,14 @@ const creditGrant = async (orgId, amount, source) => {
   if (!isValidOrgId(orgId)) return { doc: null, applied: false };
   if (!Number.isFinite(amount) || amount <= 0) throw new Error('invalid argument: amount must be a positive finite number');
   if (typeof source !== 'string' || source.trim() === '') throw new Error('invalid argument: source must be a non-empty string');
+  // Validate source against the enum before writing — findOneAndUpdate does not run validators.
+  BillingExtraBalanceSchema.ExtraBalanceCreditGrant.parse({ orgId, amount, source: source.trim() });
 
-  const idempotencyKey = `${source}-${orgId}`;
+  const idempotencyKey = `${source.trim()}-${orgId}`;
   const entry = {
     kind: 'topup',
     amount,
-    source,
+    source: source.trim(),
     refId: idempotencyKey,
     at: new Date(),
   };

modules/billing/tests/billing.extraBalance.unit.tests.js

@@ -881,6 +881,13 @@ describe('BillingExtraBalance unit tests:', () => {
         ).rejects.toThrow('invalid argument: source must be a non-empty string');
       });
 
+      test('should throw (Zod) on source value not in allowed enum', async () => {
+        await expect(
+          BillingExtraBalanceRepository.creditGrant(orgId, 500, 'freebie'),
+        ).rejects.toThrow();
+        expect(mockModel.findOneAndUpdate).not.toHaveBeenCalled();
+      });
+
       test('should return null doc with applied:false for invalid orgId', async () => {
         const { default: mongoose } = await import('mongoose');
         mongoose.Types.ObjectId.isValid = jest.fn(() => false);