@dhyasama/totem-models 12.25.0 → 12.27.0

package/lib/Account.js

@@ -77,6 +77,19 @@ module.exports = function(mongoose, config) {
       sendSystemEmails: { type: Boolean, default: false },
     },
 
+    // Granola native REST API integration. Keys are per-user, so they live on
+    // the account: when active, webhooks polls this user's Granola notes using
+    // apiKey (see webhooks/src/granola). Opt-in — only synced when a key is set.
+    granola: {
+      active: { type: Boolean, default: false },
+      apiKey: { type: String, trim: true, default: '' },
+      // Sync watermark, machine-written by the webhooks poller (same pattern as
+      // auth.google.nextSyncToken). Only ever update it via a targeted
+      // $set: { 'granola.updatedAfter': ... } — a blind rewrite of the whole
+      // granola subdocument (e.g. from a settings form) would clobber it.
+      updatedAfter: { type: Date, default: null }
+    },
+
     summary: {
       active: { type: Boolean, default: false }
     }

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/lib/Organization.js

@@ -225,13 +225,6 @@ module.exports = function(mongoose, config) {
           active: { type: Boolean, default: false }
         },
 
-        // Granola native REST API integration. When active, webhooks polls this
-        // customer's Granola notes using apiKey (see webhooks/src/granola).
-        granola: {
-          active: { type: Boolean, default: false },
-          apiKey: { type: String, trim: true }
-        },
-
         sheet: {
           id: { type: String, trim: true, unique: true, partialFilterExpression : { type :"string" } },
           format: {

package/package.json

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

package/scripts/audit-metric-currency-scale.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * READ-ONLY audit for the snapshot -> metric currency/scale migration.
+ *
+ * Reports how many snapshots and metrics are missing currency/scale, and the distribution of
+ * values present. Run this BEFORE the backfill to see how many metrics would receive the
+ * default ('USD' / 1) rather than a real snapshot value.
+ *
+ * Makes NO writes.
+ *
+ * Usage:
+ *   node scripts/audit-metric-currency-scale.js [<customerId>] [--config <path>]
+ *   node scripts/audit-metric-currency-scale.js --config ../totem-web/config/config.js
+ *   DB_URI="mongodb://..." node scripts/audit-metric-currency-scale.js
+ */
+
+const mongoose = require('mongoose');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const CUSTOMER_ID = (args[0] && !args[0].startsWith('--')) ? args[0] : null;
+
+let dbUri = null;
+const configIndex = args.indexOf('--config');
+if (configIndex !== -1 && args[configIndex + 1]) dbUri = require(path.resolve(args[configIndex + 1])).db.uri;
+if (!dbUri && process.env.DB_URI) dbUri = process.env.DB_URI;
+if (!dbUri) { console.error('Error: --config or DB_URI required'); process.exit(1); }
+
+console.log('Audit scope:', CUSTOMER_ID ? `customer ${CUSTOMER_ID}` : 'ALL customers');
+console.log('Database URI:', dbUri.replace(/\/\/[^:]+:[^@]+@/, '//*****:*****@'), '\n');
+
+mongoose.connect(dbUri);
+const db = mongoose.connection;
+db.on('error', (err) => { console.error('MongoDB connection error:', err); process.exit(1); });
+db.once('open', async () => {
+  try { await audit(db); process.exit(0); }
+  catch (err) { console.error('Audit failed:', err); process.exit(1); }
+});
+
+// A field is "missing" if absent or null (empty string counted separately as its own bucket).
+const isNull = (f) => ({ $eq: [{ $ifNull: [f, null] }, null] });
+
+async function audit(db) {
+  const Financials = db.collection('financials');
+  const match = CUSTOMER_ID ? { customer: new mongoose.Types.ObjectId(CUSTOMER_ID) } : {};
+
+  const docs = await Financials.countDocuments(match);
+
+  // ---- snapshot level ----
+  const [snap] = await Financials.aggregate([
+    { $match: match },
+    { $unwind: '$snapshots' },
+    { $group: {
+        _id: null,
+        total: { $sum: 1 },
+        missingCurrency: { $sum: { $cond: [isNull('$snapshots.currency'), 1, 0] } },
+        emptyCurrency: { $sum: { $cond: [{ $eq: ['$snapshots.currency', ''] }, 1, 0] } },
+        missingScale: { $sum: { $cond: [isNull('$snapshots.scale'), 1, 0] } },
+    } },
+  ]).toArray();
+
+  // ---- metric level (what the backfill actually writes) ----
+  const [met] = await Financials.aggregate([
+    { $match: match },
+    { $unwind: '$snapshots' },
+    { $unwind: '$snapshots.metrics' },
+    { $group: {
+        _id: null,
+        total: { $sum: 1 },
+        missingCurrency: { $sum: { $cond: [isNull('$snapshots.metrics.currency'), 1, 0] } },
+        missingScale: { $sum: { $cond: [isNull('$snapshots.metrics.scale'), 1, 0] } },
+        // metrics whose snapshot ALSO lacks currency -> these get the 'USD' default on backfill
+        metricAndSnapshotMissingCurrency: { $sum: { $cond: [{ $and: [isNull('$snapshots.metrics.currency'), isNull('$snapshots.currency')] }, 1, 0] } },
+    } },
+  ]).toArray();
+
+  // ---- distribution of snapshot currency/scale values present ----
+  const curDist = await Financials.aggregate([
+    { $match: match }, { $unwind: '$snapshots' },
+    { $group: { _id: '$snapshots.currency', n: { $sum: 1 } } }, { $sort: { n: -1 } },
+  ]).toArray();
+  const scaleDist = await Financials.aggregate([
+    { $match: match }, { $unwind: '$snapshots' },
+    { $group: { _id: '$snapshots.scale', n: { $sum: 1 } } }, { $sort: { n: -1 } },
+  ]).toArray();
+
+  const s = snap || { total: 0, missingCurrency: 0, emptyCurrency: 0, missingScale: 0 };
+  const m = met || { total: 0, missingCurrency: 0, missingScale: 0, metricAndSnapshotMissingCurrency: 0 };
+  const pct = (a, b) => b ? (100 * a / b).toFixed(1) + '%' : '0%';
+
+  console.log('=== Financials ===');
+  console.log(`  documents: ${docs}`);
+  console.log('\n=== Snapshots ===');
+  console.log(`  total:              ${s.total}`);
+  console.log(`  missing currency:   ${s.missingCurrency} (${pct(s.missingCurrency, s.total)})`);
+  console.log(`  empty-string currency: ${s.emptyCurrency}`);
+  console.log(`  missing scale:      ${s.missingScale} (${pct(s.missingScale, s.total)})`);
+  console.log('\n=== Metrics (what the backfill writes) ===');
+  console.log(`  total:              ${m.total}`);
+  console.log(`  missing currency:   ${m.missingCurrency} (${pct(m.missingCurrency, m.total)})  <- will be backfilled`);
+  console.log(`  missing scale:      ${m.missingScale} (${pct(m.missingScale, m.total)})  <- will be backfilled`);
+  console.log(`  missing currency AND snapshot has none -> would get 'USD' default: ${m.metricAndSnapshotMissingCurrency}`);
+  console.log('\n=== Snapshot currency distribution ===');
+  curDist.forEach((c) => console.log(`  ${JSON.stringify(c._id)}: ${c.n}`));
+  console.log('\n=== Snapshot scale distribution ===');
+  scaleDist.forEach((c) => console.log(`  ${JSON.stringify(c._id)}: ${c.n}`));
+}

package/scripts/backfill-metric-currency-scale.js

@@ -0,0 +1,193 @@
+'use strict';
+
+/**
+ * SAFE, STANDALONE backfill: snapshot-level currency/scale -> per-metric currency/scale.
+ *
+ * For every metric that does not already carry its own `currency`/`scale`, copy it down from the
+ * (now-deprecated) snapshot-level `currency`/`scale`. Also backfills the metric's `previous`
+ * sub-state when present (so undo round-trips), and normalizes any null/absent snapshot-level
+ * `scale` to 1 (a null scale already means "unscaled" = 1) so no null scales remain anywhere.
+ * A missing snapshot `scale` yields metric `scale: 1`; a missing snapshot `currency` yields 'USD'
+ * (per the prod audit this never occurs — every snapshot has a real currency).
+ *
+ * Why a dedicated script (not scripts/migrate-financials-schema.js): that script bundles 11 other
+ * transformations, including a metric "convert branch" that rebuilds the whole metrics array and can
+ * DROP already-migrated metrics in a mixed-state snapshot. This script has NO such path — it only
+ * adds fields, never rewrites arrays or removes anything. It is:
+ *   - additive      : only ever $set's currency/scale on metrics that lack them
+ *   - idempotent    : re-running is a no-op
+ *   - value-safe    : never touches metric.value/breakdown/etc.; no displayed number changes
+ *     (metric.currency := snapshot.currency, which read paths already fall back to today)
+ *
+ * Usage:
+ *   node scripts/backfill-metric-currency-scale.js <customerId> [--config <path>] [--dry-run]
+ *   node scripts/backfill-metric-currency-scale.js --all-customers --config <path> [--dry-run]
+ *   DB_URI="mongodb://..." node scripts/backfill-metric-currency-scale.js <customerId> --dry-run
+ *
+ * ALWAYS run with --dry-run first and inspect the output.
+ */
+
+// Valid metric scales (must match the enum in lib/Financials.js). A corrupt legacy snapshot scale
+// is sanitized to 1 rather than propagated into a metric (which would fail a future validated write).
+const VALID_METRIC_SCALES = [1, 1000, 1000000, 1000000000, 1000000000000];
+function sanitizeScale(scale) {
+  return VALID_METRIC_SCALES.includes(scale) ? scale : 1;
+}
+
+/**
+ * Pure function: compute the $set backfill for a single financials document.
+ * Returns { updates: {dotPath: value}, changes: [string] }. Empty updates => nothing to do.
+ * No DB access, so this is directly unit-testable.
+ */
+function computeBackfillUpdates(financial) {
+  const updates = {};
+  const changes = [];
+  if (!financial || !Array.isArray(financial.snapshots)) return { updates, changes };
+
+  financial.snapshots.forEach((snapshot, i) => {
+    if (!snapshot) return;
+
+    const currency = snapshot.currency || 'USD';
+    const scale = sanitizeScale(snapshot.scale);
+
+    // Normalize a null/absent/invalid snapshot-level scale to 1 so no null scales remain anywhere
+    // (a null scale already means "unscaled" = 1, so this is a value-safe cleanup).
+    if (!VALID_METRIC_SCALES.includes(snapshot.scale)) {
+      updates[`snapshots.${i}.scale`] = 1;
+      changes.push(`  - snapshot ${i}: scale ${JSON.stringify(snapshot.scale)} -> 1`);
+    }
+
+    if (!Array.isArray(snapshot.metrics)) return;
+    snapshot.metrics.forEach((metric, j) => {
+      if (!metric) return;
+
+      if (!('currency' in metric)) {
+        updates[`snapshots.${i}.metrics.${j}.currency`] = currency;
+        changes.push(`  - snapshot ${i} metric ${j} (${metric.name}): currency := ${currency}`);
+      }
+      if (!('scale' in metric)) {
+        updates[`snapshots.${i}.metrics.${j}.scale`] = scale;
+        changes.push(`  - snapshot ${i} metric ${j} (${metric.name}): scale := ${scale}`);
+      }
+
+      // Backfill the prior-state sub-doc too, so undo restores currency/scale rather than unsetting them.
+      const prev = metric.previous;
+      if (prev && typeof prev === 'object') {
+        if (!('currency' in prev)) {
+          updates[`snapshots.${i}.metrics.${j}.previous.currency`] = currency;
+          changes.push(`  - snapshot ${i} metric ${j} (${metric.name}): previous.currency := ${currency}`);
+        }
+        if (!('scale' in prev)) {
+          updates[`snapshots.${i}.metrics.${j}.previous.scale`] = scale;
+          changes.push(`  - snapshot ${i} metric ${j} (${metric.name}): previous.scale := ${scale}`);
+        }
+      }
+    });
+  });
+
+  return { updates, changes };
+}
+
+module.exports = { computeBackfillUpdates, sanitizeScale };
+
+// ---------------------------------------------------------------------------
+// DB runner (only when executed directly, so the pure logic above stays testable)
+// ---------------------------------------------------------------------------
+if (require.main === module) {
+  const mongoose = require('mongoose');
+  const path = require('path');
+
+  const args = process.argv.slice(2);
+  const DRY_RUN = args.includes('--dry-run');
+  const ALL_CUSTOMERS = args.includes('--all-customers');
+  const CUSTOMER_ID = (args[0] && !args[0].startsWith('--')) ? args[0] : null;
+
+  let configPath = null;
+  let dbUri = null;
+
+  const configIndex = args.indexOf('--config');
+  if (configIndex !== -1 && args[configIndex + 1]) configPath = path.resolve(args[configIndex + 1]);
+  const dbUriIndex = args.indexOf('--db-uri');
+  if (dbUriIndex !== -1 && args[dbUriIndex + 1]) dbUri = args[dbUriIndex + 1];
+  if (!dbUri && process.env.DB_URI) dbUri = process.env.DB_URI;
+
+  if (!CUSTOMER_ID && !ALL_CUSTOMERS) {
+    console.error('Error: provide a <customerId> or --all-customers');
+    process.exit(1);
+  }
+  if (configPath) {
+    console.log(`Loading config from: ${configPath}`);
+    dbUri = require(configPath).db.uri;
+  }
+  if (!dbUri) {
+    console.error('Error: --config, --db-uri, or DB_URI is required');
+    process.exit(1);
+  }
+
+  console.log('Backfill Configuration:');
+  console.log('  Scope:', ALL_CUSTOMERS ? 'ALL customers' : `customer ${CUSTOMER_ID}`);
+  console.log('  Database URI:', dbUri.replace(/\/\/[^:]+:[^@]+@/, '//*****:*****@'));
+  console.log('  Dry Run:', DRY_RUN);
+  console.log('');
+
+  mongoose.connect(dbUri);
+  const db = mongoose.connection;
+  db.on('error', (err) => { console.error('MongoDB connection error:', err); process.exit(1); });
+  db.once('open', async () => {
+    console.log('Connected to MongoDB');
+    try {
+      await run(db);
+      console.log('\nBackfill completed successfully!');
+      process.exit(0);
+    } catch (err) {
+      console.error('\nBackfill failed:', err);
+      process.exit(1);
+    }
+  });
+
+  async function run(db) {
+    const Financials = db.collection('financials');
+    const query = ALL_CUSTOMERS ? {} : { customer: new mongoose.Types.ObjectId(CUSTOMER_ID) };
+    const financials = await Financials.find(query).toArray();
+    console.log(`Found ${financials.length} financial document(s)\n`);
+
+    // Detailed per-field logging is far too noisy at prod scale (100k+ writes), so print full
+    // detail only for the first few changed docs as a sample (or all docs with --verbose), and
+    // otherwise track category totals derived from the update key suffixes.
+    const VERBOSE = process.argv.includes('--verbose');
+    const SAMPLE_DOCS = 3;
+    let changed = 0, unchanged = 0, fieldWrites = 0;
+    let metricCurrency = 0, metricScale = 0, prevWrites = 0, snapshotScaleFixes = 0;
+
+    for (const financial of financials) {
+      const { updates, changes } = computeBackfillUpdates(financial);
+      const keys = Object.keys(updates);
+      if (keys.length === 0) { unchanged++; continue; }
+      fieldWrites += keys.length;
+      keys.forEach((k) => {
+        if (/\.metrics\.\d+\.currency$/.test(k)) metricCurrency++;
+        else if (/\.metrics\.\d+\.scale$/.test(k)) metricScale++;
+        else if (/\.previous\./.test(k)) prevWrites++;
+        else if (/^snapshots\.\d+\.scale$/.test(k)) snapshotScaleFixes++;
+      });
+
+      if (!DRY_RUN) await Financials.updateOne({ _id: financial._id }, { $set: updates });
+
+      if (VERBOSE || changed < SAMPLE_DOCS) {
+        console.log(`${DRY_RUN ? '[DRY RUN] would update' : 'updated'} ${financial._id} (${keys.length} writes)${(!VERBOSE && changed === SAMPLE_DOCS - 1) ? '  [sample; further per-doc detail suppressed]' : ''}`);
+        changes.forEach((c) => console.log(c));
+        console.log('');
+      }
+      changed++;
+    }
+
+    console.log('=== Backfill Summary ===');
+    console.log(`Documents ${DRY_RUN ? 'that would change' : 'changed'}: ${changed} / ${financials.length} (already complete: ${unchanged})`);
+    console.log(`Total field writes: ${fieldWrites}`);
+    console.log(`  metric currency:      ${metricCurrency}`);
+    console.log(`  metric scale:         ${metricScale}`);
+    console.log(`  metric.previous:      ${prevWrites}`);
+    console.log(`  snapshot null-scale->1: ${snapshotScaleFixes}`);
+    if (DRY_RUN) console.log('\nThis was a dry run. No changes were made.');
+  }
+}

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);
   });