@dhyasama/totem-models 12.26.0 → 12.27.0

package/lib/Financials.js

@@ -76,12 +76,6 @@ module.exports = function(mongoose, config) {
 
       uuid: { type: String },
 
-      // DEPRECATED: currency/scale now live per-metric (see metrics[].currency / metrics[].scale).
-      // Retained during the dual-write transition as the fallback default for un-migrated metrics;
-      // remove once all read paths resolve currency/scale per metric.
-      currency: { type: String, default: 'USD' },
-      scale: { type: Number, enum: [1, 1000, 1000000, 1000000000, 1000000000000], default: 1 },
-
       approval:{ type: Boolean, default: false },
 
       status: { type: String, enum: ['Scheduled', 'Delivered', 'Opened', 'Overdue', 'Skipped', 'Pending', 'Completed', 'Archived'] },
@@ -148,9 +142,7 @@ module.exports = function(mongoose, config) {
           }
         }],
         verified: { type: Boolean, default: false },
-        // Per-metric currency/scale. Intentionally NO defaults: an undefined value means
-        // "not yet migrated" and read paths fall back to the (deprecated) snapshot-level
-        // currency/scale. See scripts/migrate-financials-schema.js for the backfill.
+        // Currency and scale live exclusively on each metric/scenario.
         currency: { type: String, trim: true },
         scale: { type: Number, enum: [1, 1000, 1000000, 1000000000, 1000000000000] },
         history: [{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhyasama/totem-models",
-  "version": "12.26.0",
+  "version": "12.27.0",
   "author": "Jason Reynolds",
   "license": "UNLICENSED",
   "description": "Models for Totem platform",

package/scripts/libs/financial_metric_units.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const VALID_METRIC_SCALES = [1, 1000, 1000000, 1000000000, 1000000000000];
+const UNITLESS_METRIC_NAMES = new Set(['Months of Runway']);
+
+const sanitizeScale = (scale) => VALID_METRIC_SCALES.includes(scale) ? scale : 1;
+const isUnitlessMetricName = (name) => UNITLESS_METRIC_NAMES.has(name);
+
+const getMetricUnits = (metricName, snapshot = {}) => {
+  if (isUnitlessMetricName(metricName)) {
+    return { currency: undefined, scale: 1 };
+  }
+  return { currency: snapshot.currency || 'USD', scale: sanitizeScale(snapshot.scale) };
+};
+
+module.exports = {
+  getMetricUnits,
+  isUnitlessMetricName,
+  sanitizeScale
+};
+

package/scripts/migrate-financials-schema.js

@@ -25,6 +25,8 @@
  *     currency/scale. Idempotent: metrics that already carry their own are left untouched.
  *     Defaults to 'USD' / 1 when the snapshot has neither. Part of the snapshot→metric
  *     currency migration (dual-write transition; snapshot fields retained as fallback).
+ *     Unitless metrics (currently Months of Runway) are normalized to scale 1 with no currency,
+ *     including their optional previous/undo state.
  *
  * Usage:
  *   node scripts/migrate-financials-schema.js <customerId> [--config <configPath>] [--dry-run]
@@ -40,6 +42,7 @@
 
 const mongoose = require('mongoose');
 const path = require('path');
+const { getMetricUnits, isUnitlessMetricName, sanitizeScale } = require('./libs/financial_metric_units');
 
 // Parse command line arguments
 const args = process.argv.slice(2);
@@ -85,14 +88,6 @@ if (configPath) {
   dbUri = config.db.uri;
 }
 
-// Valid metric scales (must match the enum in lib/Financials.js). The backfill sanitizes the
-// snapshot's stored scale against this set so a corrupt legacy value can't propagate into a
-// metric and fail a future validated write. Unknown/absent values fall back to 1.
-const VALID_METRIC_SCALES = [1, 1000, 1000000, 1000000000, 1000000000000];
-function sanitizeScale(scale) {
-  return VALID_METRIC_SCALES.includes(scale) ? scale : 1;
-}
-
 console.log('Migration Configuration:');
 console.log('  Customer ID:', CUSTOMER_ID);
 console.log('  Database URI:', dbUri.replace(/\/\/[^:]+:[^@]+@/, '//*****:*****@')); // Mask credentials
@@ -323,10 +318,8 @@ async function migrateFinancials() {
             oldMetrics.forEach((metric) => {
               const source = getSourceForMetric(metric.name);
 
-              // Create separate metric entries for each scenario that has a value
-              // Backfill per-metric currency/scale from the (now-deprecated) snapshot-level values
-              const metricCurrency = snapshot.currency || 'USD';
-              const metricScale = sanitizeScale(snapshot.scale);
+              // Create separate metric entries for each scenario that has a value.
+              const metricUnits = getMetricUnits(metric.name, snapshot);
 
               if ('actual' in metric && metric.actual !== undefined && metric.actual !== null) {
                 const newMetric = {
@@ -334,11 +327,11 @@ async function migrateFinancials() {
                   scenario: 'actual',
                   value: metric.actual,
                   breakdown: metric.breakdown || {},
-                  currency: metricCurrency,
-                  scale: metricScale,
+                  scale: metricUnits.scale,
                   verified: true,
                   history: historyArrayForMetrics
                 };
+                if (metricUnits.currency) newMetric.currency = metricUnits.currency;
                 if (source) newMetric.sources = [source];
                 newMetrics.push(newMetric);
               }
@@ -349,11 +342,11 @@ async function migrateFinancials() {
                   scenario: 'budget',
                   value: metric.budget,
                   breakdown: {},
-                  currency: metricCurrency,
-                  scale: metricScale,
+                  scale: metricUnits.scale,
                   verified: true,
                   history: historyArrayForMetrics
                 };
+                if (metricUnits.currency) newMetric.currency = metricUnits.currency;
                 if (source) newMetric.sources = [source];
                 newMetrics.push(newMetric);
               }
@@ -364,11 +357,11 @@ async function migrateFinancials() {
                   scenario: 'forecast',
                   value: metric.forecast,
                   breakdown: {},
-                  currency: metricCurrency,
-                  scale: metricScale,
+                  scale: metricUnits.scale,
                   verified: true,
                   history: historyArrayForMetrics
                 };
+                if (metricUnits.currency) newMetric.currency = metricUnits.currency;
                 if (source) newMetric.sources = [source];
                 newMetrics.push(newMetric);
               }
@@ -395,16 +388,48 @@ async function migrateFinancials() {
                   changes.push(`  - Snapshot ${index}: Added sources to metric ${mIndex} (${metric.name})`);
                 }
               }
-              // Backfill per-metric currency/scale from the (now-deprecated) snapshot-level values.
-              // Idempotent: only set when the metric doesn't already carry its own.
-              if (!('currency' in metric)) {
-                updates[`snapshots.${index}.metrics.${mIndex}.currency`] = snapshot.currency || 'USD';
-                changes.push(`  - Snapshot ${index}: Backfilled currency (${snapshot.currency || 'USD'}) to metric ${mIndex} (${metric.name})`);
-              }
-              if (!('scale' in metric)) {
-                const backfillScale = sanitizeScale(snapshot.scale);
-                updates[`snapshots.${index}.metrics.${mIndex}.scale`] = backfillScale;
-                changes.push(`  - Snapshot ${index}: Backfilled scale (${backfillScale}) to metric ${mIndex} (${metric.name})`);
+              const metricUnits = getMetricUnits(metric.name, snapshot);
+              if (isUnitlessMetricName(metric.name)) {
+                if ('currency' in metric) {
+                  updates.$unset = updates.$unset || {};
+                  updates.$unset[`snapshots.${index}.metrics.${mIndex}.currency`] = '';
+                  changes.push(`  - Snapshot ${index}: Removed currency from unitless metric ${mIndex} (${metric.name})`);
+                }
+                if (metric.scale !== 1) {
+                  updates[`snapshots.${index}.metrics.${mIndex}.scale`] = 1;
+                  changes.push(`  - Snapshot ${index}: Set unitless scale (1) on metric ${mIndex} (${metric.name})`);
+                }
+                if (metric.previous && typeof metric.previous === 'object') {
+                  if ('currency' in metric.previous) {
+                    updates.$unset = updates.$unset || {};
+                    updates.$unset[`snapshots.${index}.metrics.${mIndex}.previous.currency`] = '';
+                    changes.push(`  - Snapshot ${index}: Removed currency from previous state for unitless metric ${mIndex} (${metric.name})`);
+                  }
+                  if (metric.previous.scale !== 1) {
+                    updates[`snapshots.${index}.metrics.${mIndex}.previous.scale`] = 1;
+                    changes.push(`  - Snapshot ${index}: Set unitless scale (1) on previous state for metric ${mIndex} (${metric.name})`);
+                  }
+                }
+              } else {
+                // Idempotent: only set when the money metric doesn't already carry its own units.
+                if (!('currency' in metric)) {
+                  updates[`snapshots.${index}.metrics.${mIndex}.currency`] = metricUnits.currency;
+                  changes.push(`  - Snapshot ${index}: Backfilled currency (${metricUnits.currency}) to metric ${mIndex} (${metric.name})`);
+                }
+                if (!('scale' in metric)) {
+                  updates[`snapshots.${index}.metrics.${mIndex}.scale`] = metricUnits.scale;
+                  changes.push(`  - Snapshot ${index}: Backfilled scale (${metricUnits.scale}) to metric ${mIndex} (${metric.name})`);
+                }
+                if (metric.previous && typeof metric.previous === 'object') {
+                  if (!('currency' in metric.previous)) {
+                    updates[`snapshots.${index}.metrics.${mIndex}.previous.currency`] = metricUnits.currency;
+                    changes.push(`  - Snapshot ${index}: Backfilled previous currency (${metricUnits.currency}) on metric ${mIndex} (${metric.name})`);
+                  }
+                  if (!('scale' in metric.previous)) {
+                    updates[`snapshots.${index}.metrics.${mIndex}.previous.scale`] = metricUnits.scale;
+                    changes.push(`  - Snapshot ${index}: Backfilled previous scale (${metricUnits.scale}) on metric ${mIndex} (${metric.name})`);
+                  }
+                }
               }
             });
           }

package/test/FinancialMetricUnits.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const assert = require('assert');
+const {
+  getMetricUnits,
+  isUnitlessMetricName,
+  sanitizeScale
+} = require('../scripts/libs/financial_metric_units');
+
+describe('financial metric migration units', function() {
+  it('stores Months of Runway as unscaled units without currency', function() {
+    assert.strictEqual(isUnitlessMetricName('Months of Runway'), true);
+    assert.deepStrictEqual(
+      getMetricUnits('Months of Runway', { currency: 'EUR', scale: 1000 }),
+      { currency: undefined, scale: 1 }
+    );
+  });
+
+  it('inherits snapshot units for money metrics', function() {
+    assert.deepStrictEqual(
+      getMetricUnits('Revenue', { currency: 'EUR', scale: 1000 }),
+      { currency: 'EUR', scale: 1000 }
+    );
+  });
+
+  it('sanitizes absent and invalid scales', function() {
+    assert.strictEqual(sanitizeScale(undefined), 1);
+    assert.strictEqual(sanitizeScale(123), 1);
+    assert.strictEqual(sanitizeScale(1000000), 1000000);
+  });
+});
+

package/test/Financials.js

@@ -15,6 +15,27 @@ var orgB = new mongoose.Types.ObjectId();
 
 describe('Financials', function() {
 
+  it('does not define or persist snapshot-level currency and scale', function() {
+    var f = new Financials({
+      organization: orgA,
+      customer: customerA,
+      snapshots: [{
+        uuid: 'metric-units-only',
+        year: 2025,
+        period: 'FY',
+        currency: 'EUR',
+        scale: 1000,
+        metrics: [{ name: 'Revenue', scenario: 'actual', value: 10, currency: 'EUR', scale: 1000 }]
+      }]
+    });
+
+    var snapshot = f.snapshots[0].toObject();
+    should.not.exist(snapshot.currency);
+    should.not.exist(snapshot.scale);
+    snapshot.metrics[0].currency.should.equal('EUR');
+    snapshot.metrics[0].scale.should.equal(1000);
+  });
+
   before(function(done) {
     databaseHelpers.connect(mongoose, done);
   });