feat(billing): compute layer foundation - PR-N1 (no behavior change) (#3535)

* feat(billing): compute layer foundation - pr-n1 (no behavior change)

lays the foundational data layer for compute-based pricing behind
the billing.computeMode: false feature flag (default off).
all new code paths are dormant for existing downstream projects.

new models: billing.plan.model.mongoose.js + schema, billing.processedStripeEvent.model.mongoose.js

modified models (additive, sparse, backward-compat): billing.usage (weekKey,
computeUsed/Quota, computeBreakdown, resetAt, alertedAt80/100, consumedHistoryIds),
billing.subscription (planVersion, currentPeriodStart, pastDueSince)

new service: billing.plan.service.js - getActivePlan (1h cache), getPlanByVersion,
bumpVersion (mongo transaction), invalidateCache; billing.plans.service.js kept as legacy facade

config: billing.computeMode (default false), billing.compute.*, billing.packs,
stripe.prices.packs (all downstream override slots)

migrations: 20260501000000 (weekKey sparse index), 20260501000100 (plan/event indexes) - idempotent

tests: +43 tests across 3 new suites + 3 extended existing files

closes checklist item pr-n1 in #3533

* fix(billing): remove duplicate index creation from migrations

Migrations were creating indexes with custom names (planId_version_unique,
organizationId_weekKey_unique_sparse) that conflicted with the auto-names
Mongoose assigns at bootstrap (planId_1_version_1, organizationId_1_weekKey_1).
MongoDB code 85 IndexOptionsConflict was crashing the app on first run in
each fresh test DB, causing all integration tests to fail.

These indexes are owned by the Mongoose schemas and auto-synced at connect
time — the migration up() functions must not duplicate them.

* fix(billing): make migrations pure no-ops - all indexes are Mongoose-managed

The subscriptions.planVersion sparse index and processedstripeevents.processedAt
TTL index are both defined in Mongoose schemas with autoIndex:true. When
migrations run post-connect, Mongoose has already created them with auto-names
(planVersion_1, processedAt_1). The migrations tried to create the same key
patterns with different names → IndexOptionsConflict code 85.

Both migrations are now pure markers (up/down no-ops). The schema + index
lifecycle is fully owned by Mongoose model definitions.

* test(billing): remove done callbacks from synchronous Zod schema tests

New Subscription compute-field tests used the done callback pattern from
surrounding legacy tests, but the operations are synchronous (safeParse).
Using done with sync code masks exceptions as timeouts rather than failures.
Replaced with plain synchronous test functions to fix 6 Codacy ErrorProne
high findings.

* fix(billing): address CodeRabbit major + minor findings on billing.plan.service

Major fixes:
- bumpVersion: remove withTransaction/startSession (requires replica set).
  Now uses updateMany + countDocuments + create without sessions, matching
  the standalone-MongoDB pattern in organizations.membership.service.js.
- getActivePlan: do not cache null results (plan not found) — a null miss
  should not block visibility of a newly-created plan until TTL expiry.
  Reduce CACHE_TTL from 1h to 5min to limit stale-read window.
- billing.plan.model: add Mongoose validator on ratios (must be object with
  finite non-negative values). Mirror in Zod schema with .min(0).

Minor fixes:
- Add JSDoc header to makeDoc test helper.
- Fix misleading test title for fetchPlansFromStripe (not exported).
- Add test coverage for negative ratio rejection.
- Fix BillingPlanBump JSDoc: ratios is optional, not required.
- Update bumpVersion tests to reflect no-session implementation.

* fix(billing): suppress Codacy false-positive useQwikValidLexicalScope on Node service

Codacy applies Biome's useQwikValidLexicalScope rule to Node.js arrow
function declarations, producing 6 ErrorProne high findings. This rule
is designed for Qwik SSR serialization and is a false positive in a
Node.js context. Add biome-ignore suppressions to the affected
top-level function declarations in billing.plan.service.js and its
unit test file. No behavior change.

* refactor(billing): apply critical-review fixes — repository pattern + meter rename

- Extract BillingPlanRepository (findActive, findByVersion, deactivateAll, count, create)
  so billing.plan.service.js no longer imports mongoose directly (ERRORS.md arch rule)
- Rename compute → meter throughout billing module for devkit neutrality:
  computeMode → meterMode, compute.* → meter.*, computeQuota → meterQuota,
  computeUsed/computeQuota/computeBreakdown → meterUsed/meterQuota/meterBreakdown
- git mv migration to 20260501000000-add-meter-fields.js (history preserved)
- Update unit tests to mock repository instead of mongoose; add lean() pass-through test
- Add JSDoc: bumpVersion concurrency/activation-gap guidance, getActivePlan null semantics,
  dollarsToUnitRatio downstream-override warning, multi-pod cache stale-window TODO
- Backward compat: meterMode default false, zero behavior change for non-meter downstream

* fix(billing): add biome-ignore suppressions for useQwikValidLexicalScope on repository + service

Codacy erroneously applies the Qwik rule on Node.js module-level arrow
functions. Suppress in billing.plan.repository.js (6 declarations) and
restore suppressions removed from billing.plan.service.js (4 declarations)
during the refactor → 0 high ErrorProne issues expected.

* fix(billing): address CodeRabbit Major/Critical findings on indexes + schema

1. BillingPlanMongoose: make (planId, active, effectiveUntil) a partial unique
   index (active=true, effectiveUntil=null) — enforces single active plan per
   planId at the DB level, guards concurrent bumpVersion() races.

2. BillingUsage: scope (organizationId, month) unique index to non-meter docs
   only (partialFilterExpression: weekKey $exists false) — allows multiple
   weekly records per month in meter mode.

3. BillingPlanBump schema: add .min(0) to ratios values — matches BillingPlan
   validation contract, prevents negative ratio overrides bypassing Zod.

4. billing.plan.repository.js: add JSDoc to BillingPlan() model accessor.

5. Add test: BillingPlanBump.ratios rejects negative values.

* test(billing): add unit tests for billing.plan.repository.js

Add 10 tests covering all 5 repository methods (findActive, findByVersion,
deactivateAll, count, create) to fix Codecov patch coverage below 80%
threshold on the new repository file.

* docs(billing): align stale 'Compute fields' comment with meter rename

Author: PierreBrisorgueil

modules/billing/config/billing.development.config.js

@@ -25,6 +25,38 @@ const config = {
       'unpaid',
       'paused',
     ],
+    /**
+     * Feature flag — default OFF.
+     * Set to true in downstream project config to enable meter-based pricing.
+     * When false, all meter code paths are no-ops; legacy behavior unchanged.
+     */
+    meterMode: false,
+    /**
+     * Meter unit parameters — downstream projects must override with their
+     * actual unit economics before enabling meterMode in production.
+     *
+     * runBaseUnits: flat units charged per run (before per-feature ratios).
+     * maxUnitsPerOperation: safety cap per single operation run.
+     */
+    meter: {
+      runBaseUnits: 1,
+      /**
+       * Conversion ratio: 1 unit = 1 / dollarsToUnitRatio USD of underlying cost.
+       *
+       * DOWNSTREAM-OVERRIDE-REQUIRED — the devkit default (1000) is illustrative.
+       * Each downstream project must set this based on their unit economics
+       * (cost-target × margin multiplier). Setting this wrong directly affects
+       * gross margin: a value of N means each $1 of cost consumes N units, so
+       * lowering N halves the margin coverage.
+       */
+      dollarsToUnitRatio: 1000,
+      maxUnitsPerOperation: 10000,
+    },
+    /**
+     * Extra meter packs — downstream projects override with actual packs.
+     * Example: [{ packId: 'pack_500k', meterUnits: 500000, stripePriceId: 'price_xxx' }]
+     */
+    packs: [],
   },
   stripe: {
     secretKey: process.env.DEVKIT_NODE_stripe_secretKey ?? '',
@@ -38,6 +70,11 @@ const config = {
         monthly: process.env.DEVKIT_NODE_stripe_prices_pro_monthly ?? '',
         annual: process.env.DEVKIT_NODE_stripe_prices_pro_annual ?? '',
       },
+      /**
+       * Extra packs price map — downstream project override.
+       * Example: { pack_500k: 'price_xxx', pack_2m: 'price_yyy' }
+       */
+      packs: {},
     },
   },
 };

modules/billing/migrations/20260501000000-add-meter-fields.js

@@ -0,0 +1,28 @@
+/**
+ * Migration: Add meter fields to billing_usages collection
+ *
+ * Adds weekKey, meterUsed, meterQuota, planVersion, meterBreakdown,
+ * resetAt, alertedAt80, alertedAt100, consumedHistoryIds to existing documents.
+ *
+ * The (organizationId, weekKey) sparse unique index is owned by the Mongoose
+ * schema and synced at bootstrap — do not duplicate it here (name mismatch
+ * causes IndexOptionsConflict).
+ *
+ * Additive only — no data backfill (existing documents keep legacy values).
+ * Idempotent: safe to run multiple times.
+ *
+ * @returns {Promise<void>}
+ */
+export async function up() {
+  // No raw index creation needed: all billingusages indexes are managed by the
+  // Mongoose BillingUsage model and auto-synced on connection.
+  // No document backfill: new fields have defaults in the Mongoose schema
+  // (meterUsed: 0, meterQuota: 0, meterBreakdown: {}, consumedHistoryIds: []).
+  // Existing documents without these fields will use Mongoose defaults on read.
+}
+
+/**
+ * Down: no-op — indexes are Mongoose-managed; fields are additive (one-way safe).
+ * @returns {void}
+ */
+export function down() {}

modules/billing/migrations/20260501000100-add-plan-version-and-period-start.js

@@ -0,0 +1,22 @@
+/**
+ * Migration: Add planVersion and currentPeriodStart to subscriptions collection
+ *
+ * Schema changes (new fields + indexes on subscriptions, billingplans,
+ * processedstripeevents) are owned by the respective Mongoose models and
+ * auto-synced at bootstrap (autoIndex: true).
+ *
+ * This migration is a marker: it records the point at which these fields
+ * were introduced so rollback tooling can target the correct state.
+ *
+ * Additive only — no data backfill.
+ * Idempotent: safe to run multiple times.
+ *
+ * @returns {void}
+ */
+export function up() {}
+
+/**
+ * Down: no-op — indexes are Mongoose-managed; fields are additive (one-way safe).
+ * @returns {void}
+ */
+export function down() {}

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

@@ -0,0 +1,113 @@
+/**
+ * Module dependencies
+ */
+import mongoose from 'mongoose';
+
+const Schema = mongoose.Schema;
+
+/**
+ * BillingPlan Data Model Mongoose
+ *
+ * Versioned plan definitions for meter-based pricing.
+ * Each (planId, version) pair is immutable after creation.
+ * Use bumpVersion to create a new version and deactivate the previous one.
+ */
+const BillingPlanMongoose = new Schema(
+  {
+    planId: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    version: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    meterQuota: {
+      type: Number,
+      required: true,
+      min: 0,
+    },
+    stripePriceMonthly: {
+      type: String,
+      trim: true,
+      sparse: true,
+    },
+    stripePriceAnnual: {
+      type: String,
+      trim: true,
+      sparse: true,
+    },
+    /**
+     * Flexible ratio map for meter unit attribution.
+     * Each key is a feature name; each value is a non-negative finite number.
+     * Example: { scrap: 1, autofix: 2, wizard: 5 }
+     */
+    ratios: {
+      type: Schema.Types.Mixed,
+      default: () => ({}),
+      validate: {
+        validator(value) {
+          return (
+            value != null &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            Object.values(value).every((n) => Number.isFinite(n) && n >= 0)
+          );
+        },
+        message: 'ratios must be an object whose values are finite numbers >= 0',
+      },
+    },
+    effectiveFrom: {
+      type: Date,
+      required: true,
+    },
+    effectiveUntil: {
+      type: Date,
+      default: null,
+    },
+    active: {
+      type: Boolean,
+      default: true,
+      index: true,
+    },
+  },
+  {
+    timestamps: true,
+  },
+);
+
+/**
+ * Unique index per (planId, version) — immutable identity
+ */
+BillingPlanMongoose.index({ planId: 1, version: 1 }, { unique: true });
+
+/**
+ * Compound index to look up the active plan for a given planId efficiently.
+ * Partial unique constraint: only one active plan per planId at a time
+ * (effectiveUntil: null means currently active). Guards against concurrent
+ * bumpVersion() races producing two simultaneously-active versions.
+ */
+BillingPlanMongoose.index(
+  { planId: 1, active: 1, effectiveUntil: 1 },
+  { unique: true, partialFilterExpression: { active: true, effectiveUntil: null } },
+);
+
+/**
+ * Returns the hex string representation of the document ObjectId.
+ * @returns {string} Hex string of the ObjectId.
+ */
+function addID() {
+  return this._id.toHexString();
+}
+
+/**
+ * Model configuration
+ */
+BillingPlanMongoose.virtual('id').get(addID);
+BillingPlanMongoose.set('toJSON', {
+  virtuals: true,
+});
+
+mongoose.model('BillingPlan', BillingPlanMongoose);

modules/billing/models/billing.plan.schema.js

@@ -0,0 +1,38 @@
+/**
+ * Module dependencies
+ */
+import { z } from 'zod';
+
+/**
+ * BillingPlan Zod schema — mirrors billing.plan.model.mongoose.js
+ */
+
+const BillingPlan = z.object({
+  planId: z.string().trim().min(1, 'planId is required'),
+  version: z.string().trim().min(1, 'version is required'),
+  meterQuota: z.number().int().min(0, 'meterQuota must be >= 0'),
+  stripePriceMonthly: z.string().trim().optional().nullable(),
+  stripePriceAnnual: z.string().trim().optional().nullable(),
+  ratios: z.record(z.string(), z.number().min(0, 'ratio values must be >= 0')).default(() => ({})),
+  effectiveFrom: z.coerce.date(),
+  effectiveUntil: z.coerce.date().nullable().optional(),
+  active: z.boolean().default(true),
+});
+
+/**
+ * Schema for bumping to a new plan version.
+ * meterQuota is required; all other fields are optional overrides.
+ */
+const BillingPlanBump = z
+  .object({
+    meterQuota: z.number().int().min(0),
+    ratios: z.record(z.string(), z.number().min(0, 'ratio values must be >= 0')).optional(),
+    stripePriceMonthly: z.string().trim().optional().nullable(),
+    stripePriceAnnual: z.string().trim().optional().nullable(),
+  })
+  .strict();
+
+export default {
+  BillingPlan,
+  BillingPlanBump,
+};

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

@@ -0,0 +1,61 @@
+/**
+ * Module dependencies
+ */
+import mongoose from 'mongoose';
+
+const Schema = mongoose.Schema;
+
+/**
+ * ProcessedStripeEvent Data Model Mongoose
+ *
+ * Idempotency store for Stripe webhook events.
+ * TTL of 30 days — events older than that can safely be re-processed
+ * (Stripe's webhook retry window is 3 days).
+ */
+const ProcessedStripeEventMongoose = new Schema(
+  {
+    eventId: {
+      type: String,
+      required: true,
+      unique: true,
+      trim: true,
+    },
+    type: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    processedAt: {
+      type: Date,
+      required: true,
+      default: () => new Date(),
+    },
+  },
+  {
+    timestamps: false,
+    // Disable _id virtuals to keep the document lean
+  },
+);
+
+/**
+ * TTL index: automatically remove documents 30 days after processedAt
+ */
+ProcessedStripeEventMongoose.index({ processedAt: 1 }, { expireAfterSeconds: 30 * 24 * 60 * 60 });
+
+/**
+ * Returns the hex string representation of the document ObjectId.
+ * @returns {string} Hex string of the ObjectId.
+ */
+function addID() {
+  return this._id.toHexString();
+}
+
+/**
+ * Model configuration
+ */
+ProcessedStripeEventMongoose.virtual('id').get(addID);
+ProcessedStripeEventMongoose.set('toJSON', {
+  virtuals: true,
+});
+
+mongoose.model('ProcessedStripeEvent', ProcessedStripeEventMongoose);

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

@@ -44,6 +44,33 @@ const SubscriptionMongoose = new Schema(
       type: Boolean,
       default: false,
     },
+
+    // ── Meter fields (sparse — backward-compatible additions) ────────────────
+
+    /**
+     * The plan version active on this subscription (e.g. "v1", "v2").
+     * Only populated when meterMode is enabled.
+     */
+    planVersion: {
+      type: String,
+      sparse: true,
+    },
+    /**
+     * Start of the current billing period. Used to detect period changes
+     * in webhook handlers and trigger meter period resets.
+     */
+    currentPeriodStart: {
+      type: Date,
+      default: null,
+    },
+    /**
+     * Timestamp when the subscription first entered past_due status.
+     * Used to enforce the 7-day grace period before degraded mode.
+     */
+    pastDueSince: {
+      type: Date,
+      default: null,
+    },
   },
   {
     timestamps: true,

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

@@ -20,6 +20,10 @@ const baseShape = {
   stripeCustomerId: optionalStripeId,
   stripeSubscriptionId: optionalStripeId,
   currentPeriodEnd: z.coerce.date().nullable().optional(),
+  // ── Meter fields (optional — backward-compatible) ────────────────────────
+  planVersion: z.string().trim().optional(),
+  currentPeriodStart: z.coerce.date().nullable().optional(),
+  pastDueSince: z.coerce.date().nullable().optional(),
 };
 
 const Subscription = z.object({